Monday, May 20, 2024
 Popular · Latest · Hot · Upcoming
43
rated 0 times [  50] [ 7]  / answers: 1 / hits: 38808  / 11 Years ago, mon, october 7, 2013, 12:00:00

I've been trying to use JSDoc3 to generate documentation on a file, but I'm having some difficulty. The file (which is a Require.js module) basically looks like this:



define([], function() {

/*
* @exports mystuff/foo
*/
var foo = {
/**
* @member
*/
bar: {
/**
* @method
*/
baz: function() { /*...*/ }
}
};

return foo;
}


The problem is, I can't get baz to show up in the generated documentation. Instead I just get a documentation file for a foo/foo module, which lists a bar member, but bar has no baz (just a link to foo's source code).



I've tried changing bar's directive to @property instead, and I've tried changing baz's directive to @member or @property, but none of that helps. No matter what I do, baz just doesn't seem to want to show up.



Does anyone know what directive structure I could use to get baz to appear in the generated documentation?



P.S. I've tried reading pages like this one on the JSDoc site http://usejsdoc.org/howto-commonjs-modules.html, but it only describes cases of foo.bar, not foo.bar.baz.


More From » requirejs

 Answers
10

You can use a combination of @module or @namespace along with @memberof.



define([], function() {

/**
* A test module foo
* @version 1.0
* @exports mystuff/foo
* @namespace foo
*/
var foo = {
/**
* A method in first level, just for test
* @memberof foo
* @method testFirstLvl
*/
testFirstLvl: function(msg) {},
/**
* Test child object with child namespace
* @memberof foo
* @type {object}
* @namespace foo.bar
*/
bar: {
/**
* A Test Inner method in child namespace
* @memberof foo.bar
* @method baz
*/
baz: function() { /*...*/ }
},
/**
* Test child object without namespace
* @memberof foo
* @type {object}
* @property {method} baz2 A child method as property defination
*/
bar2: {
/**
* A Test Inner method
* @memberof foo.bar2
* @method baz2
*/
baz2: function() { /*...*/ }
},
/**
* Test child object with namespace and property def.
* @memberof foo
* @type {object}
* @namespace foo.bar3
* @property {method} baz3 A child method as property defination
*/
bar3: {
/**
* A Test Inner method in child namespace
* @memberof foo.bar3
* @method baz3
*/
baz3: function() { /*...*/ }
},
/**
* Test child object
* @memberof foo
* @type {object}
* @property {method} baz4 A child method
*/
bar4: {
/**
* The @alias and @memberof! tags force JSDoc to document the
* property as `bar4.baz4` (rather than `baz4`) and to be a member of
* `Data#`. You can link to the property as {@link foo#bar4.baz4}.
* @alias bar4.baz4
* @memberof! foo#
* @method bar4.baz4
*/
baz4: function() { /*...*/ }
}
};

return foo;
});


EDIT as per Comment: (Single page solution for module)



bar4 without that ugly property table. ie @property removed from bar4.



define([], function() {

/**
* A test module foo
* @version 1.0
* @exports mystuff/foo
* @namespace foo
*/
var foo = {
/**
* A method in first level, just for test
* @memberof foo
* @method testFirstLvl
*/
testFirstLvl: function(msg) {},
/**
* Test child object
* @memberof foo
* @type {object}
*/
bar4: {
/**
* The @alias and @memberof! tags force JSDoc to document the
* property as `bar4.baz4` (rather than `baz4`) and to be a member of
* `Data#`. You can link to the property as {@link foo#bar4.baz4}.
* @alias bar4.baz4
* @memberof! foo#
* @method bar4.baz4
*/
baz4: function() { /*...*/ },
/**
* @memberof! for a memeber
* @alias bar4.test
* @memberof! foo#
* @member bar4.test
*/
test : true
}
};

return foo;
});


References -




  1. Another Question about nested namespaces

  2. For alternative way of using Namespaces

  3. Documenting literal objects



*Note I haven't tried it myself. Please try and share the results.


[#75169] Sunday, October 6, 2013, 11 Years  [reply] [flag answer]
Only authorized users can answer the question. Please sign in first, or register a free account.
grayson

Total Points: 36
Total Questions: 113
Total Answers: 95

Location: Tonga
Member since Fri, Aug 21, 2020
4 Years ago
grayson questions
;