如何使用 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 为包含其他对象的对象创建子页面，从而使最终用户无法阅读文档。

因为，类工厂使用诸如mixins之类的对象（几乎）我决定将根页面声明为@mixin，我可以使用@object-如果有人测试过，请在这里给出一些反馈......

此外，我希望读者将注意力从单词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!

      }
   };
}

我自己的 cmets 有足够的空间，这与我最初的评论没有太大区别。这也是不言自明的。

结果：

这个文件的菜单只有一个链接hybrid :))

我使用的标签：@mixin、@var、@memberof、@prop、@function、@param、@return、@summary 和 @desc。

我还避免使用更多标签使代码混乱，并使用不同标识符的命名空间，例如 g3.hybrid.constructor 替换 @static 或 g3.hybrid~addLibrary 替换 @inner。

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