Каков наилучший способ использования jsduck для документирования обработчиков событий?

Question

Каков наилучший вид заголовка jsduck для размещения метода класса (такого как подкласс ExtJS), который обрабатывает событие? Jsduck поддерживает те же теги, что и jsdoc, но я не уверен, что тег @event уместен.

Answer 1

Тег @event в JSDuck и jsdoc-toolkit предназначен для одного и того же - документирования событий, запускаемых классом.

Хотя в этой части документы jsdoc-toolkit выглядят немного запутанно, выражение @event "описывает событие, обрабатываемое классом" , которое может выглядеть так, как будто оно предназначено для документирования слушателей. Но, глядя на jsdoc-toolkit журнал проблем , мы видим, что эта функция была вдохновлена ​​событиями в YUI, и поскольку ExtJS также вырос из YUI, он подтверждает семантическое равенство тега @event в обоих jsdoc- инструментарий и JSDuck.

Однако вы, похоже, спрашиваете об обработчиках событий - методах, которые зарегистрированы для обработки событий, запускаемых другими классами. Как будто у вас есть метод showPopup, и вы хотите документально подтвердить, что этот метод обрабатывает событие click для некоторой кнопки. Это противоположно тому, для чего предназначен тег @event.

Но вы действительно не должны документировать ваши обработчики событий каким-либо особым образом - достаточно просто документировать их как обычные методы. Это то же самое, что документировать, какие другие методы вызывают определенный метод - иногда полезно предоставить эту информацию, но делать это для всех методов просто глупо.

Вкратце. Методы и события являются интерфейсом для класса - они должны документироваться. Регистрация обработчиков событий и методов вызова - это то, как вы используете интерфейс - это деталь реализации, не документируйте ее (по крайней мере, не на том же уровне, что ваша документация API).

Answer 2

Обработчик событий должен быть задокументирован так же, как и любой другой метод (@method и т. Д.).@event - это тег, который вы бы использовали для прослушиваемого события:

function Foo() {
    /**
     * Fired when a sandwich is made
     * @event sandwich-made
     * @param {my.ns.Sandwich} sandwich
     */
    this.listen('sandwich-made', this.onSandwichMade, this);
}

Когда вы документируете свои события, это субъективно.Вы можете сделать это, как я делал выше, если это единственная точка входа в это событие, или , как показано в документации JsDuck , когда имена событий фактически объявляются, если вы добавляете их формально с помощью addEvents(events) method.

Документы не являются явными, но предположительно любой тег @event, встречающийся в контексте данного объекта, будет связан с этим объектом.