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

javascript, js-amd, jsdoc, requirejs

Solution

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.

Problem

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?

Original source