How to document a Require.js (AMD) Modul with jsdoc 3 or jsdoc?

Question

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?

Answer 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.