javascript - JSDocはコールバック関数にリンクします

原文 javascript node.js jsdoc

JSDocを使用して、作業中のプロジェクトを文書化することにしました。ここで使用ガイドと質問を読みながら、私はJSDocのコアコンセプトの一部を理解していないように感じ、次の例で自分の無能さを示しました:http://jsfiddle.net/zsbtykpv/

/**
 * @module testModule
 */

/**
 * @constructor
 */
var Test = function() {
    /**
     * @callback myCallback
     * @param {Object} data An object that contains important data.
     */

    /**
     * A method that does something async
     * @param  {myCallback} cb a callback function
     * @return {boolean} always returns true
     */
    this.method = function(cb) {
        doSomethingAsync(function(data) {
            cb(data);
        });
        return true;
    }

}

module.exports = Test;


ここでは、モジュールを定義し、コンストラクタを示し、コールバックをパラメータの1つとして受け取るメソッドをドキュメント化しました。非常にシンプルに聞こえ、使用ガイドhttp://usejsdoc.org/によって設定されたガイドラインに従っているように見えます。

しかし、私の理解を超えた何らかの理由で(そしておそらくそれは私が理解していないコアコンセプトです)、コールバックmyCallbackをTestクラスの代わりにtestModuleのメンバーとして表示します。デフォルトではなく、モジュールのクラスのメンバーである必要がありますか?また、これはJSDocがコールバック定義へのリンクを作成するのを妨げているように見えますが、これはそれほど楽しいことではありません。

今、私が書こうとすると、

/**
 * @callback module:testModule~Test~myCallback
 * @param {Object} data An object that contains important data.
 */

/**
 * A method that does something async
 * @param  {module:testModule~Test~myCallback} cb a callback function
 * @return {boolean} always returns true
 */


私は私の希望する行動をとるでしょう。しかし、これは非常に不格好な方法であるように思われ、生成されたリンクはかなりきれいではありません。

長い蓄積のため申し訳ありませんが、私の文書化の取り組みにご協力いただきありがとうございます:)
答え
私はほとんど同じ問題に遭遇しました。見栄えの良いリンクが必要な場合は、いつでも{@link}を説明に追加し、次のように@typeで正規名を使用できます。

/**
 * @callback module:testModule~Test~myCallback
 * @param {Object} data An object that contains important data.
 */

/**
 * @param {myCallback} cb {@link module:testModule~Test~myCallback|myCallback}: a callback function
 * @return {boolean} always returns true
 */


タイプするのは少しイライラしますが、myCallbackはモジュールではなくクラスのメンバーとして記述されており、リンクは見栄えがします。

@type内のリンクが本当に必要で、コールバックをどのようにドキュメント化するかを気にしない場合は、これを行うこともできます。これは少し冗長ではありません(そして私がプロジェクトで行うことを決めたものです)。

/**
 * @callback myCallback
 * @param {Object} data An object that contains important data.
 */

/**
 * @param {module:testModule~myCallback} cb a callback function
 * @return {boolean} always returns true
 */


これにより、myCallbackに正しくリンクされ、モジュールのメンバーとしてドキュメント化されます。
関連記事

javascript - JavaScript + Unicode正規表現

javascript - バックエンドサービスに同じ呼び出しを行う複数のブラウザースクリプトを処理するには

javascript - angularjsの名前とタイトルに従ってデータをフィルタリングする方法は?

javascript - console.logを呼び出すときにChromeスタックトレースをだましてリダイレクトする方法はありますか?

java - Android-Webview HTMLコード抽出が機能しない(Javascript)

javascript - 他のフレームセットからフレームを隠す

javascript - Snap.svgとjavascriptがキャッチされないSyntaxErrorをスローする

javascript - 入力日付カレンダーを拡張します(ブラウザーネイティブ)

javascript - AngularJSの確認モーダル

javascript - jQueryカーソルを水平方向にDIVで追跡します