75

編集: これは技術的には 2 つの部分からなる質問です。一般的な質問をカバーする最良の回答を選択し、特定の質問を処理する回答にリンクしました。

jsdocで匿名オブジェクトと関数を文書化する最良の方法は何ですか?

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};

PageRequestオブジェクトもcallbackコード内の存在もありません。それらはgetPage()実行時に提供されます。しかし、オブジェクトと機能が何であるかを定義できるようにしたいと考えています。

PageRequest次のことを文書化するためのオブジェクトを作成することから逃れることができます。

/**
 * @namespace {PageRequest} Object specification
 * @property {String} pageId ID of the page you want.
 * @property {String} pageName Name of the page you want.
 */
var PageRequest = {
    pageId : null,
    pageName : null
};

それは問題ありません (ただし、これを行うためのより良い方法を受け入れます)。

callback関数を文書化する最良の方法は何ですか? たとえば、コールバック関数が次の形式であることを文書で知らせたいと思います。

callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus)

これを行う方法はありますか?

4

6 に答える 6

63

@name タグを使用して、コードに存在しないものを文書化できます。

/**
 * Description of the function
 * @name IDontReallyExist
 * @function
 * @param {String} someParameter Description
*/

/**
 * The CallAgain method calls the provided function twice
 * @param {IDontReallyExist} func The function to call twice
*/
exports.CallAgain = function(func) { func(); func(); }

@name タグのドキュメントは次のとおりです。名前パスも役立つ場合があります。

于 2010-08-22T20:44:00.353 に答える
2

@linkメソッドとクラスへのインラインリンクを追加できます。

/**
 * Get a page from the server
 * @param {PageRequest} pageRequest Info on the page you want to request
 * @param {function} callback Function executed when page is retrieved<br />
 * function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus)
 */
this.getPage = function (pageRequest, callback) {
};

理想的ではありませんが、それは仕事を成し遂げます。

于 2010-07-06T19:07:55.370 に答える
0

@see を使用して、同じクラス内の別のメソッドにリンクできます。このメソッドは使用されることはなく、ドキュメントの目的でのみ存在します。

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     * @see #getPageCallback 
     */
    this.getPage = function (pageRequest, callback) {
    }; 

    /**
     * Called when page request completes 
     * @param {PageResponse} pageResponse The requested page
     * @param {PageRequestStatus} pageRequestStatus Status of the page
     */
    //#ifdef 0
    this.getPageCallback = function (pageResponse, pageRequestStatus) { };
    //#endif 
};

ある種のビルド システムを使用している場合、ダミー メソッドはビルドから簡単に省略できます。

于 2010-07-06T01:33:26.923 に答える