如何使用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 。

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