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!

      }
   };
}

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

结果：

此单个文件的菜单只有一个链接hybrid：））

我使用过的代码：@mixin，@var，@memberof，@prop，@function，@param，@return，{ {1}}和@summary。

我还避免使用更多标签来混淆我的代码，并使用@desc等不同标识符的命名空间替换g3.hybrid.constructor或@static重新定位g3.hybrid~addLibrary。< / p>

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

如何使用jsdoc注释工厂类使用的自定义对象

1 个答案: