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;
}