jsdoc：如何獲取實例方法參數？

Question

我試圖用JSDoc3記錄一些舊代碼，而我卻試圖使它在文檔中包含實例方法的參數-或根本不顯示任何實例屬性。 我懷疑問題在於代碼沒有遵循仿造javascript類的預期習慣，但是我想在開始重寫任何內容之前先記錄所有內容。 我試圖用實際代碼的結構來舉一個小問題的例子：

/**
 * Global function
 * @param  {Object} v Stuff that they're trying to avoid making global
 * @return {Object}   Updated v
 */
jsdoc_test = function( v ) {
    /**
     * Some stuff is defined in this namespace
     * @namespace space
     */
    var space = {};
    /**
     * Something that acts like a class
     * @name space.someclass
     * @memberOf space
     * @constructor
     * @type {function}
     * @param  {any}    y blah blah
     * @return {Object}   The constructed object
     */
    space.someclass = function( w ) {
        var obj = {
            source:  w,        // might need this again
            derived: foo( w ), // what we usually need
            etc:     "etc"     // and so on
        };
        /**
         * This should be a member function, but it appears as a static property
         * @name space.someclass.methodA
         * @memberOf space.someclass
         * @type {function}
         * @instance
         * @param  {any}    x Parameters do not appear in documentation
         * @return {Object}   this
         */
        obj.methodA = function( x ) {
            bar( x ); // or whatever methodA does
            return this;
        }
        /**
         * This should be a member function, but it doesn't show up at all
         * @name space.someclass.methodB
         * @memberOf space.someclass#
         * @type {function}
         * @param  {any}    y Parameters do not appear in documentation
         * @return {Object}   this
         */
        obj.methodB = function( y ) {
            baz( y ); // or whatever methodB does
            return this;
        }
        return obj;
        /**
         * This should be a member function, but it doesn't show up at all
         * @name space.someclass.methodC
         * @memberOf space.someclass.prototype
         * @type {function}
         * @param  {any}    z Parameters do not appear in documentation
         * @return {Object}   this
         */
        obj.methodC = function( z ) {
            qux( z ); // or whatever methodC does
            return this;
        }
        return obj;
    }
    // ...
}

我希望所有這三種方法都作為實例方法出現在生成的文檔中。 實際上， methodA看起來是靜態屬性，而methodB和methodC （遵循此處的建議）根本不出現

如何在不重寫代碼的情況下使JSDoc3用實例參數記錄實例方法？

Answer 1

看起來您在代碼上使用了太多標記。 使用@constructor ，您不需要@name或@type ，因為使用構造函數可以覆蓋這些內容。

因此，我認為您有兩種選擇。

使用@constructor並刪除冗余（沖突）標簽：

/**
 * Something that acts like a class
 * @constructor space.someclass
 * @memberOf space
 * @param  {any}    y blah blah
 * @return {Object}   The constructed object
 */

或者，如果您不想使用@constructor標記，請自己添加適當的提示：

/**
 * Something that acts like a class
 * @name space.someclass
 * @memberOf space
 * @kind class
 * @param  {any}    y blah blah
 * @return {Object}   The constructed object
 */

在這兩種情況下， @type都是多余的，因為您正在記錄一個類。 從技術上講，類型將是函數的全名（即@type {space.someclass} ）。

Answer 2

@ instance，@ memberOf和@method的組合應該可以做到：

/**
 * This should now be a member function.
 * @instance
 * @memberOf space.someclass
 * @method methodA
 * @param {*} x Some parameter of any type.
 * @return {Object} this.
 */