46

JSDoc3 を使用してファイルに関するドキュメントを生成しようとしていますが、問題が発生しています。ファイル (Require.js モジュール) は、基本的に次のようになります。

define([], function() {

    /*
     * @exports mystuff/foo
     */
    var foo = {
        /**
         * @member
         */
        bar: {
            /**
             * @method
             */
            baz: function() { /*...*/ }
        }
    };

    return foo;
}

baz問題は、生成されたドキュメントに表示されないことです。代わりに、メンバーfoo/fooをリストするモジュールのドキュメント ファイルを取得するだけですが、メンバーはありません(のソース コードへのリンクのみ)。barbarbazfoo

barのディレクティブを@property代わりに変更しようとしましたが、のディレクティブをまたはに変更しようとしましたbazが@member、@propertyどれも役に立ちません。私が何をしても、baz は現れたくないようです。

生成されたドキュメントに baz を表示するために使用できるディレクティブ構造を知っている人はいますか?

PS JSDoc サイトhttp://usejsdoc.org/howto-commonjs-modules.htmlでこのようなページを読んでみましたがfoo.bar、 ではなくのケースのみを説明していfoo.bar.bazます。

4

4 に答える 4

8

これを行う簡単な方法は次のとおりです。

/**
 * @module mystuff/foo
 * @version 1.0
 */
define([], function() {

/** @lends module:mystuff/foo */
var foo = {
    /**
     * A method in first level, just for test
     */
    testFirstLvl: function(msg) {},
    /**
     * @namespace
     */
    bar4: {
        /**
         * This is the description for baz4.
         */
        baz4: function() { /*...*/ },
        /**
         * This is the description for test.
         */
        test : true
    }
};

return foo;
});

jsdoc は、@method と @member を言わなくても、型baz4.baz4を推測できることに注意してください。test

jsdoc3 でクラスと名前空間のドキュメントを、それらを定義するモジュールと同じページに配置する限り、私はそれを行う方法がわかりません。

私は jsdoc3 を何ヶ月も使用しており、小さなライブラリと大規模なアプリケーションをドキュメント化しています。私は、@-ディレクティブを大量に入力して自分の意志に曲げるよりも、いくつかの領域でjsdoc3の意志に曲げることを好みます。

于 2013-11-07T01:02:37.347 に答える
1

ネストされた関数を直接文書化することはできません。私は Prongs ソリューションが気に入らなかったので、名前空間のない別の実装を使用しました ( JavaではなくJS です!)。

アップデート：

OPで指定された正確なユースケースを反映するように回答を更新しました（JSdocは使用するのがかなり面倒なので、これは公平です）。それがどのように機能するかは次のとおりです。

/** @module foobar */

/** @function */
function foobarbaz() {
    /* 
     * You can't document properties inside a function as members, like you
     * can for classes. In Javascript, functions are first-class objects. The
     * workaround is to make it a @memberof it's closest parent (the module).
     * manually linking it to the function using (see: {@link ...}), and giving
     * it a @name.
     */

    /**
     * Foo object (see: {@link module:foobar~foobarbaz})
     * @name foo
     * @inner
     * @private
     * @memberof module:foobar
     * @property {Object} foo - The foo object
     * @property {Object} foo.bar - The bar object
     * @property {function} foo.bar.baz - The baz function
     */
    var foo = {

        /* 
         * You can follow the same steps that was done for foo, with bar. Or if the
         * @property description of foo.bar is enough, leave this alone. 
         */
        bar: {

            /*
             * Like the limitation with the foo object, you can only document members 
             * of @classes. Here I used the same technique as foo, except with baz.
             */

            /**
             * Baz function (see: {@link module:foobar~foo})
             * @function
             * @memberof module:foobar
             * @returns {string} Some string
             */
            baz: function() { /*...*/ }
        }
    };

    return foo;
}

残念ながら、JSdoc は Java のポートであるため、Java には意味があっても JS には意味がない、またはその逆の多くの機能があります。たとえば、JS では関数はファーストクラスのオブジェクトであるため、オブジェクトまたは関数として扱うことができます。したがって、次のようなことを行うとうまくいくはずです：

/** @function */
function hello() {
  /** @member {Object} */
  var hi = {};
}

しかし、JSdoc はそれを関数として認識するため、そうはなりません。名前空間、私のテクニックを使用@linkするか、クラスにする必要があります。

/** @class */
function Hello() {
  /** @member {Object} */
  var hi = {};
}

しかし、それも意味がありません。クラスはJSに存在しますか? いいえ、そうではありません。

より良いドキュメント ソリューションを見つける必要があると思います。{object}型の表示方法 ( vsなど)に関するドキュメントに矛盾があることさえ見てきました{Object}。

私のテクニックを使ってクロージャーを文書化することもできます。

于 2014-12-17T02:18:22.067 に答える
0

JSDoc3に対するProngsの回答を少し改善するために、 @memberの代わりに@instanceアノテーションを使用した場合にのみ機能させることができました。

ES6 のサンプル コードは次のとおりです。

class Test
{
    /**
     * @param {object} something
     */
    constructor(something)
    {
        this.somethingElse = something;

        /**
         * This sub-object contains all sub-class functionality.
         *
         * @type {object}
         */
        this.topology = {
            /**
             * Informative comment here!
             *
             * @alias topology.toJSON
             * @memberof! Test#
             * @instance topology.toJSON
             * 
             * @returns {object} JSON object
             */
            toJSON()
            {
                return deepclone(privatesMap.get(this).innerJSON);
            },


            ...
        }
    }
}
于 2016-10-02T13:59:03.253 に答える