如何使用jsdoc注釋工廠類使用的自定義對象

Question

我有一個自定義對象g3.hybrid ，工廠函數g3.Class會將其用作生成自定義類的父對象。

我的問題是，在此對象填充工廠函數后，我無法使JSDoc識別我的函數/屬性。

這是我的自定義對象：

/**
 * @class g3.hybrid
 * @classdesc
 * A supplementary object used as parent for the class construction helper class 
 * (see {@link g3.Class}).
 * bla-bla-bla
 */
g3.hybrid = function(myClass){ //<-No, this is NOT constructor!
  return {
    /**
     * @lends g3.hybrid.
     */
    STATIC: { //<-It's members WILL become static props!
       /**
        * @static
        * @prop {Object} defaults Accessed as: g3[myClass].defaults
        * @prop {string} defaults.name Name of stored object, should provide your own names
        */
       defaults: {
          name: 'g3hybrid'
       }
    },
    /**
     * @lends g3.hybrid.prototype
     */
    prototype: { //<- It's members WILL become prototype members!
       /**
        * @public
        * @function g3.hybrid.prototype.addLibrary
        * It is called always implicitly from a library plugin of "g3[myClass]".
        * bla-bla-bla
        * @param {String} name A name of the library that each object stores in 
        * instance property libraries.
        * @param {String} lib A reference of an object from a library.
        * @return {} Undefined.
        */
       addLibrary: function(name, lib){
       }
    },

      /**
       * @public
       * @constructs g3.hybrid
       * @function g3.hybrid.constructor
       * 
       * The constructor function of "g3[myClass]".
       * You should pass an object argument or it throws an error.
       * bla-bla-bla
       * @param {Object} options Object that contains as members "name" for the 
       * instance's name and default values that will overwrite static default 
       * members.
       * @return {Object} An object of class g3[myClass].
       */
      constructor: function(options){ //<- This IS the constructor!

      }
   };
}

然后在項目的根目錄下輸入cent@cent:~/plugins$ jsdoc -c ~/node/jsdoc/conf-1.json ./js/g3hybrid-1.js -d out-plugins其中conf-1.json是我的此用戶本地安裝的node文件夾中的conf文件。

修改后的配置文件如下：

{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "include": [ /* array of paths to files to generate documentation for */ ],
        "exclude": [ /* array of paths to exclude */ ],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "sourceType": "module",
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ],
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

結果看起來像這樣：

整個方法說明成為右側面板上的鏈接

並將輔助函數function(myClass)標記為構造函數！

cent@cent:~/plugins$ jsdoc -v
JSDoc 3.5.5 (Thu, 14 Sep 2017 02:51:54 GMT)
cent@cent:~/plugins$ node -v
v7.1.0

我有什么想法可以使它變得漂亮嗎？

Answer 1

好的，我找到了答案，但是如果有人有更好的主意，我真的很想聽聽。 我決定從機器的角度對其進行評論，或者說是實際的東西，而不是將其提供給班級工廠后的樣子。

因此，我們有一個對象g3.hybrid並以此進行注釋。 我還希望為所有這些代碼提供一個頁面，因為我發現jsdoc為包含其他對象的對象創建了子頁面，使最終用戶無法閱讀文檔。

因為，類工廠使用混合對象之類的對象（幾乎），我決定將根頁面聲明為@mixin ，我本可以使用@object @mixin如果有人測試過，請在此處提供一些反饋...

此外，我希望讀者將注意力從“ STATIC一詞轉移到它的成員上，因為它們將由班級工廠變成真正的靜態成員。 換種說法，我想操縱jsdoc注釋的內容和不注釋的內容，以便讀者留在僅具有意義的內容上 。

因此，可行的評論可能是：

/**
 * @desc 
 * A supplementary object used as parent for the class construction helper class 
 * (see {@link g3.Class}).
 * 
 * bla-bla-bla
 * 
 * @mixin g3.hybrid
 */
g3.hybrid = function(myClass){ //<-No, this is NOT constructor!
   /*
    * Avoid to give jsdoc comments here as it will create a new page!
    */
   return {
      /*
       * Avoid to give jsdoc comments here as it will create a new page!
       */
      STATIC: { //<-It's members WILL become static props!
         /**
          * @summary g3.hybrid.STATIC.defaults
          * ----------------------------------
          * @desc 
          * Accessed as: g3[myClass].defaults.
          * @var {object} defaults
          * @memberof g3.hybrid
          * @prop {string} name Name of stored object, should provide your own names
          */
         defaults: {
            name: 'g3hybrid'
         }
      },

      /*
       * Avoid to give jsdoc comments here as it will create a new page!
       */
      prototype: { //<- It's members WILL become prototype members!
         /**
          * @summary 
          * g3.hybrid.prototype.addLibrary
          * ------------------------------
          * @desc 
          * It is called always implicitly from a library plugin of "g3[myClass]".
          * 
          * bla-bla-bla
          * 
          * @function g3.hybrid~addLibrary
          * @param {String} name A name of the library that each object stores in 
          * instance property libraries.
          * @param {String} lib A reference of an object from a library.
          * @return undefined
          */
         addLibrary: function(name, lib){
         }
      },

      /**
       * @summary 
       * g3.hybrid.constructor
       * ---------------------
       * @desc 
       * The constructor function of "g3[myClass]".
       * 
       * You should pass an object argument or it throws an error.
       * 
       * bla-bla-bla
       * 
       * @function g3.hybrid.constructor
       * @param {object} options Object that contains as members "name" for the 
       * instance's name and default values that will overwrite static default 
       * members.
       * @return {object} An object of class g3[myClass].
       */
      constructor: function(options){ //<- This IS the constructor!

      }
   };
}

我有足夠的空間來發表自己的評論，與我最初發表的評論沒有太大區別。 這也是不言自明的。

結果：

並且此單個文件的菜單只有一個hybrid鏈接:)）

標簽我用： @mixin ， @var ， @memberof ， @prop ， @function ， @param ， @return ， @summary和@desc 。

我也避免了雜波我的代碼以更多的標簽，我用不同的標識符的命名空間一樣g3.hybrid.constructor替換@static或g3.hybrid~addLibrary是repaces @inner 。

當然可能存在更好的方法！？