4

javadoc スタイルの文書化スタイルを使用する場合、コールバック関数に渡される引数を文書化するための規則はありますか?

/**
 * @param cb {Function} A callback that will be passed a name (String) and a Number
/
4

1 に答える 1

0

これはコールバックよりもイベントに関連していますが、関連するケースで役立つ可能性があるため、投稿したいと思いました。コールバックが呼び出されたときにイベントも発生させる場合は、このアプローチを使用してイベントを文書化できます。次に、コールバックの文書で、イベントと同じパラメーターを受け取り、@link を使用してイベントにリンクすることに注意してください。

以下に示すようなものを使用して、F.jsでイベントを文書化します。特定のコードに接続されていないため、F.Component を定義するスクリプトの最後にダンプしています。

/**
 * Triggered when this component is shown
 *
 * @name F.Component#component:shown
 * @event
 *
 * @param {Object}  evt                 Event object
 * @param {String}  evt.name            This component's name
 * @param {F.Component} evt.component   This component
 */

上記の JSDoc ステートメントは、jsdoc-toolkit を使用してビルドすると、次のようなドキュメントになります。基本的に、イベントがいつトリガーされ、どのパラメーターがコールバックに渡されるかを説明する素敵な Event Detail セクションを取得します。これは JSDoc3 でも機能し、同じ情報を含むイベント セクションが生成されます。

@event タグについて説明しているドキュメントでは、この方法で使用するように正確に説明されていませんが、目的の出力が得られることに注意してください。JSDoc3 の時点では、@ event タグと@firesタグにはまだドキュメントがありませんが、@event は私が探していた出力を提供します。

于 2012-09-11T17:05:30.637 に答える