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

Question

I have a custom object g3.hybrid that a factory function g3.Class will use it as the parent to produce custom classes.

My problem is that I can't make JSDoc to recognize what my functions/properties are going to be after this object fills the factory function.

Here is my custom object:

/**
 * @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!

      }
   };
}

Then at project's root I type cent@cent:~/plugins$ jsdoc -c ~/node/jsdoc/conf-1.json ./js/g3hybrid-1.js -d out-plugins where conf-1.json is my conf file at the node folder which is installed locally for this user.

The modified config file is as follows:

{
    "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
    }
}

The result looks like this:

The whole method description becomes a link on the right panel

and the helper function function(myClass) is marked as the constructor!

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

Any ideas that I can use to make it pretty?

Answer 1

Ok, I found an answer but if someone has a better idea I really want to hear it. I decided to comment it from the point of view of the machine or, what actually is and not what it will become after feeding it to the class factory.

So, we have an object g3.hybrid and we comment it as such. I also wanted to have, if possible, one page for all this code as I discovered that jsdoc creates sub-pages for objects that contain other objects making the documentation unreadable to the end user.

As, the class factory uses such objects as mixins (almost) I decided to declare the root page as @mixin , I could have used @object -if someone tested please give some feedback here...

Moreover, I wanted the reader to move his attention away from word STATIC and focus to it's members as these will become the real static members by the class factory; to state it differently I wanted to manipulate what jsdoc is commenting and what not so that the reader stays on what has meaning only .

As such, a viable commenting could be:

/**
 * @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!

      }
   };
}

There is enough space for my own comments and it's not big different from my initial commenting. It's also self-explanatory.

The result:

and the menu for this single file has just one link hybrid :))

Tags I used: @mixin , @var , @memberof , @prop , @function , @param , @return , @summary and @desc .

I also avoided to clutter my code with more tags and I used the namespace of the different identifiers like g3.hybrid.constructor that replaces @static or g3.hybrid~addLibrary that repaces @inner .

Of course there might exist better approaches out there!?