web-dev-qa-db-ja.com

jsdocを使用して匿名オブジェクトと関数を文書化する最良の方法

編集：これは技術的には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)
_

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

javascriptdocumentationtagsjsdoc
58
Josh Johnson

@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 tag documentation です。 name path も便利だと思うかもしれません。

44
Eric

@callback または@typedef。

/**
 * @callback arrayCallback
 * @param  {object} element - Value of array element
 * @param  {number} index   - Index of array element
 * @param  {Array}  array   - Array itself
 */

/**
 * @param {arrayCallback} callback - function applied against elements
 * @return {Array} with elements transformed by callback
 */
Array.prototype.map = function(callback) { ... }
36
kzh

Studgeekの答えを補完するために、 Google Closure Compilerを使用したJsDoc で何ができるかを示す例を提供しました。

文書化された匿名型は生成された縮小ファイルから削除され、コンパイラは有効なオブジェクトが渡されることを保証します（可能な場合）。ただし、コンパイラを使用しなくても、次の開発者やWebStorm（IntelliJ）などのツールがコンパイラを理解し、コード補完を提供するのに役立ちます。

// This defines an named type that you don't need much besides its name in the code
// Look at the definition of Page#getPage which illustrates defining a type inline
/**  @typedef { pageId : string, pageName : string, contents: string} */
var PageResponse;

/**
 * @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
     *
     * The type for the second parameter for the function below is defined inline
     *
     * @param {function(PageResponse, {statusCode: number, statusMsg: string})} callback
     *        Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};
8
Juan Mendes

Google Closure Compiler Annotationsには Type Expressions があり、これには特定の引数の型、戻り値の型、さらにはこれを示す機能が含まれます。多くのライブラリは、コードを縮小するためにそれを使用したいため、Google Closure Compilerアノテーションに従うことを検討しています。だから、いくらかの勢いがあります。欠点は、説明を提供する方法がないことです。

説明を提供するには、おそらくJSDoc Toolkit Parameters With Properties アプローチが機能します（ページの下部をご覧ください）。今私がやっていることです。 JSDoc ToolkitはV3で作業を開始する準備をしているので、そこからのフィードバックは良いかもしれません。

1
studgeek

@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) {
};

理想的ではありませんが、仕事は完了します。

1
Josh Johnson

@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 
};

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

0
Dagg Nabbit