1

イベントを処理するクラス (ExtJS サブクラスなど) のメソッドに配置するのに最適な種類の jsduck ヘッダーは何ですか? jsduck は jsdoc と同じタグをサポートしているようですが、@event タグが適切かどうかはわかりません。

4

2 に答える 2

3

@eventJSDuck と jsdoc-toolkit の両方のタグは、クラスによって起動されるイベントを文書化するという同じことを目的としています。

jsdoc-toolkit のドキュメントはこの部分で少し混乱しているように見えますが、@eventは「クラスによって処理されるイベントを記述します」と言って、リスナーを文書化するためのものであるかのように見えるかもしれません。しかし、jsdoc-toolkit の問題ログを見ると、この機能が YUI のイベントに触発されたことがわかります。また、ExtJS も YUI から派生しているため@event、jsdoc-toolkit と JSDuck の両方でタグのセマンティックな同等性が確認されています。

ただし、イベント ハンドラー (他のクラスによって発生したイベントを処理するために登録されているメソッド) について質問しているようです。メソッドがあり、このメソッドがいくつかのボタンshowPopupのイベントを処理することを文書化したい場合と同様です。clickこれは、@eventタグの目的とは反対です。

しかし、イベント ハンドラーを特別な方法で文書化するべきではありません。通常のメソッドとして文書化するだけで十分です。これは、特定のメソッドを呼び出す他のメソッドを文書化するのと同じです。この情報を提供すると便利な場合もありますが、すべてのメソッドに対してそれを行うのはばかげています。

要するに。メソッドとイベントはクラスへのインターフェイスです。ドキュメント化する必要があります。イベント ハンドラーの登録とメソッドの呼び出しは、インターフェイスの使用方法です。これは実装の詳細です。ドキュメント化しないでください (少なくとも API ドキュメントと同じレベルではありません)。

于 2013-02-11T03:20:55.130 に答える
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 docsに示されているように、イベント名が実際に宣言されている場合は、addEvents(events)メソッドで正式に追加する場合に行うことができます。

ドキュメントは明示的ではありませんが、おそらく@event、特定のオブジェクトのコンテキストで発生するタグはすべて、そのオブジェクトに関連付けられます。

于 2012-04-03T16:44:59.223 に答える