1

I have the following AMD structure for my modules.

/* globals define */
define([""], function() {
    'use strict';

    var module = {};

    function _somePrivateFunc() {}

    function somePublicFunc() {}

    module.somePublicFunc = somePublicFunc;

    return module;
});

I'm struggling with JSDoc to make it work with my modules. Until now, I could make it work like

/* globals define */
/**
 * Module description here
 * @module some/module/name
 */  
define([""], function() {
    'use strict';

    /**
     * @alias module:some/module/name
     */
    var module = {};

    function _somePrivateFunc() {}

    function somePublicFunc() {}

    /**
     * Some property description here
     * @itWorks
     */
    module.somePublicFunc = somePublicFunc;

    return module;
});

As you can see, it's working. But I want my doc comments to be defined on the function declarations instead where I add them to the module. I want to achieve this:

/* globals define */
/**
 * Module description here
 * @module some/module/name
 */
define([""], function() {
    'use strict';

    /**
     * @alias module:some/module/name
     */
    var module;

    /**
     * Somehow make this appear in JSDoc
     * @extend module:some/module/name
     * @private
     */
    function _somePrivateFunc() {}

    /**
     * Make this appear in JSDoc for sure.
     */
    function somePublicFunc() {}

    // I want this to NOT annotate, and I want the property to gather JSDoc 
    // from the func. declaration
    module = {
        somePublicFunc: somePublicFunc
    };

    return module;
});

The latter one is what I would like to achieve, but sadly it's not working :(

Any ideas? Cheers

Edit:

I made some progress. Mind, that if I write only this:

define('dep', function(require) {

    /**
     * @exports dep
     */
    var module = {};

    /**
     * Adds two numbers together.
     * @param  {Number} a the first number
     * @param  {Number} b the second number
     * @return {Number}   the sum of a and b
     */
    function sum(a, b) {
        return a + b;
    }

    module.sum = sum;

    return module;
});

then the output is empty. JSDoc can't generate the documentation properly. Although if I add a @method <name> annotation to my function, then it automagically works great. Interesting, but adding only a @method annotation without a name is not sufficient enough. My final working solution looks like:

define('dep', function(require) {

    /**
     * @exports dep
     */
    var module = {};

    /**
     * Adds two numbers together.
     * @func sum
     * @param  {Number} a the first number
     * @param  {Number} b the second number
     * @return {Number}   the sum of a and b
     */
    function sum(a, b) {
        return a + b;
    }

    /**
     * Creates a closure. Adds two numbers together
     * @func _add
     * @param {Number} a the closure variable to add statically
     * @return {Function} the closure
     * @private
     */
    function _add(a) {
        return function(b) {
            return a + b;
        };
    }

    module.sum = sum;

    return module;
}); 

The CLI flag -p makes the private members to appear in the documentation.

Additional info

I was able to make inner links only one way through my sample code:

/**
 * Adds two numbers together.
 * @func sum
 * @param  {Number} a the first number
 * @param  {Number} b the second number
 * @return {Number}   the sum of a and b
 * @see {@link module:dep~_add|_add}
 */
function sum(a, b) {
    return a + b;
}
Attila Kling
  • 1,717
  • 4
  • 18
  • 32
  • possible duplicate of [How to document a Require.js (AMD) Modul with jsdoc 3 or jsdoc?](http://stackoverflow.com/questions/10172381/how-to-document-a-require-js-amd-modul-with-jsdoc-3-or-jsdoc) – Louis Mar 02 '15 at 17:13
  • Thanks, but that other question doesn't answer my question at all, and it seems to be a different problem :( – Attila Kling Mar 02 '15 at 17:32
  • a) Your title here is "Using JSDoc with AMD". The other question answers that. b) Did you actually try the methods in that other question, or did you just dismiss it out of hand? If the methods failed, then how did they fail? Don't just *assert in a comment* that the other question does not solve your problem. (Which is what you just did.) *Explain in the body of your question* here how the methods in the answers on the other question failed to solve your problem. – Louis Mar 02 '15 at 17:37
  • Can you be please more specific which answer from the other thread answers my question? Since no one seems to answer mine, also I have a working solution, but that solution doesn't fit for my team's needs. :( Or maybe should I be more specific with the problem?! – Attila Kling Mar 02 '15 at 18:00

0 Answers0