How to document a Require.js (AMD) Modul with jsdo

问题:

I have 2 types of Modules:

Require.js Main File:

    require.config({
      baseUrl: "/another/path",
      paths: {
        "some": "some/v1.0"
      },
      waitSeconds: 15,
      locale: "fr-fr"
    });


    require( ["some/module", "my/module", "a.js", "b.js"],
      function(someModule,    myModule) {
      }
    );

Mediator Pattern:

define([], function(Mediator){

var channels = {};
if (!Mediator) Mediator = {};  

Mediator.subscribe = function (channel, subscription) {   
  if (!channels[channel]) channels[channel] = [];
   channels[channel].push(subscription);
};

Mediator.publish = function (channel) {
  if (!channels[channel]) return;
  var args = [].slice.call(arguments, 1);
  for (var i = 0, l = channels[channel].length; i < l; i++) {
    channels[channel][i].apply(this, args);
  }
};

return Mediator;

});

How can i document this with jsdoc3 when possible with jsdoc too?

回答1:

This is my first answer on SO, please let me know how I can improve future answers.

Your specific example

I've been searching for an answer for this for a good two days, and there doesn't seem to be a way to document RequireJS AMD modules automatically without some redundancy (like repeated function names). Karthrik's answer does a good job of generating the documentation, but if something gets renamed in the code the documentation will still be generated from what's in the jsDoc tags.

What I ended up doing is the following, which is adjusted from Karthik's example. Note the @lends tag on line 1, and the removal of the @name tag from the jsDoc comment blocks.

 define([], /** @lends Mediator */ function(Mediator){
    /** 
     * Mediator class
     * This is the interface class for user related modules
     * @class Mediator
     */

    var channels = {};
    if (!Mediator) Mediator = {};  

    /**
      * .... description goes here ...
      * @function 
      *
      * @param {Number} channel  ..... 
      * @param {String} subscription ..............
      * @example
      * add the sample code here if relevent.
      * 
      */        
    Mediator.subscribe = function (channel, subscription) {   
      if (!channels[channel]) channels[channel] = [];
       channels[channel].push(subscription);
    };

    Mediator.publish = function (channel) {
      if (!channels[channel]) return;
      var args = [].slice.call(arguments, 1);
      for (var i = 0, l = channels[channel].length; i < l; i++) {
        channels[channel][i].apply(this, args);
      }
    };

return Mediator;

});

From what I understand, the @lends tag will interpret all jsDoc comments from the next following object literal as part of the class referenced by the @lends tag. In this case the next object literal is the one beginning with function(Mediator) {. The @name tag is removed so that jsDoc looks in the source code for function names, etc.

Note: I've used the @exports tag at the same place as where I put the @lends tag. While that works, it'll create a module in the docs… and I only wanted to generate docs for the class. This way works for me!

General jsDoc references

• jsdoc-toolkit Tag Reference - Great reference for the tags in jsdoc-toolkit. Has a bunch of examples, too!
• 2ality's jsDoc intro - Comprehensive tutorial based on jsDoc-toolkit.
• jsDoc3 reference - Fairly incomplete, but has some examples.

回答2:

jsDoc doesn't seem to like the "define" and "require" calls.

So, we ended up using multiple tags to make the jsDoc tool to pick up the constructor and other specific class methods. Please have a look at the example below: I have just copy-pasted from my source-code and replaced it with your class name and method names. Hope it works for you.

    define([], function(Mediator){
        /** 
         * Mediator class
         * This is the interface class for user related modules
         * @name Mediator
         * @class Mediator
         * @constructor
         * @return Session Object
         */

        var channels = {};
        if (!Mediator) Mediator = {};  

        /**
          * .... description goes here ...
          * @name Mediator#subscribe
          * @function 
          *
          * @param {Number} channel  ..... 
          * @param {String} subscription ..............
          * @example
          * add the sample code here if relevent.
          * 
          */        
        Mediator.subscribe = function (channel, subscription) {   
          if (!channels[channel]) channels[channel] = [];
           channels[channel].push(subscription);
        };

        Mediator.publish = function (channel) {
          if (!channels[channel]) return;
          var args = [].slice.call(arguments, 1);
          for (var i = 0, l = channels[channel].length; i < l; i++) {
            channels[channel][i].apply(this, args);
          }
        };

    return Mediator;

    });

Note: The above method of documenting JS-code worked out well for us while using jsDoc. Haven't got a chance to try jsDoc3.

回答3:

Taking the link from Muxa's answer, we see that the documentation does specifically refer to RequireJS:

The RequireJS library provides a define method that allows you to write a function to return a module object. Use the @exports tag to document that all the members of an object literal should be documented as members of a module.

Module Example

define('my/shirt', function () {
   /** 
    * A module representing a shirt.
    * @exports my/shirt
    * @version 1.0
    */
    var shirt = {

        /** A property of the module. */
        color: "black",

        /** @constructor */
        Turtleneck: function(size) {
            /** A property of the class. */
            this.size = size;
        }
    };

    return shirt;
});

So in the above example, we see that jsdoc will parse a my/shirt module and document it as having two members: a property color, and also a class Turtleneck. The Turtleneck class will also be documented as having it's own property size.

Constructor Module Example

Use the @alias tag simplify documenting a constructor-module in RequireJS.

/** 
 * A module representing a jacket.
 * @module jacket
 */
define('jacket', function () {
    /**
     * @constructor
     * @alias module:jacket
     */
    var exports = function() {
    }

    /** Open and close your Jacket. */
    exports.prototype.zip = function() {
    }

    return exports;
});

The above is what you'd want to use if you are exporting a constructor function as the module which will be used as a class to instantiate objects. To sum up, I'm not sure about using the @lends and other tags/techniques that have been recommended. Instead, I would try to stick with the @module, @exports, and @alias tags used in the documentation referencing RequireJS.

I'm not sure how you should document your requirejs 'main' file. If I understand correctly, you are not actually defining any module there, but rather executing a one off function which depends on several modules.

回答4:

My AMD classes use a slightly different form, but JSDoc wasn't documenting them either so I thought I'd share what worked for me.

Constructors in the global namespace are automatically added:

/**
* @classdesc This class will be documented automatically because it is not in
* another function.
* @constructor
*/
function TestClassGlobal() {
/**
* This is a public method and will be documented automatically.
*/
this.publicMethod = function() {
};
}

If you want this behavior on a constructor inside an AMD module, declare it either as global or a member of a namespace:

define([], function() {
/**
* @classdesc This won't be automatically documented unless you add memberof,
* because it's inside another function.
* @constructor
* @memberof Namespace
*/
function TestClassNamespace() {
}

/**
* @classdesc This won't be automatically documented unless you add global,
* because it's inside another function.
* @constructor
* @global
*/
function TestClassForcedGlobal() {
}
});

回答5:

Looks like things have gotten a lot simpler in JSDoc3. The following worked for me:

Mediator as a module

/**
 * Mediator Module
 * @module Package/Mediator
 */
define([], function(Mediator){

  var channels = {};
  if (!Mediator) Mediator = {};  

  /**
   * Subscribe
   * @param  {String} channel Channel to listen to
   * @param  {Function} subscription Callback when channel updates
   * @memberOf module:Package/Mediator
   */
  Mediator.subscribe = function (channel, subscription) {   
    if (!channels[channel]) channels[channel] = [];
     channels[channel].push(subscription);
  };

  /**
   * Publish
   * @param  {String} channel  Channel that has new content
   * @memberOf module:Package/Mediator
   */
  Mediator.publish = function (channel) {
    if (!channels[channel]) return;
    var args = [].slice.call(arguments, 1);
    for (var i = 0, l = channels[channel].length; i < l; i++) {
      channels[channel][i].apply(this, args);
    }
  };

  return Mediator;

});

However, I would probably make the following change to the code:

/**
 * Mediator Module
 * @module Package/Mediator
 */
define([], function(){

  var channels = {};
  var Mediator = {}

  ...

Reason is, the module says it defines Mediator, but seems to borrow from some other instance of Mediator. I'm not sure I understand that. In this version, it's clear Mediator is defined by this file and exported.