archive-gh-me/jsdoc
1
0
Fork 0
mirror of https://github.com/jsdoc/jsdoc.git synced 2025-12-08 19:46:11 +00:00
Code Issues Projects Releases Wiki Activity

Added better support for documenting module members via @exports and @requires.

Browse Source
This commit is contained in:
Michael Mathews 2011-01-18 20:05:57 +00:00
parent d57a993a1a
commit 683e11593e
8 changed files with 118 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
modules/jsdoc/src/parser.js
View File

@ -146,10 +146,12 @@
memberof.id = 'astnode'+astnode.enclosingFunction.hashCode();
memberof.doclet = this.refs[memberof.id];
if (!memberof.doclet) return '[[anonymous]]'; // TODO handle global this?
if (!memberof.doclet) {
return '[[anonymous]]'; // TODO handle global this?
}
// walk up to the closest @constructor we can find
if (memberof.doclet.kind === 'constructor') {
if (memberof.doclet.kind === 'constructor' || memberof.doclet.kind === 'module') {
return memberof.doclet.longname||memberof.doclet.name;
}
else {

22
modules/jsdoc/tag/dictionary/definitions.js
View File

@ -93,6 +93,22 @@
}
});
dictionary.defineTag('exports', {
mustHaveValue: true,
onTagged: function(doclet, tag) {
var modName = firstWordOf(tag.value);
if ( modName.indexOf('module:') !== 0) {
modName = 'module:'+modName;
}
doclet.addTag('alias', modName);
doclet.addTag('kind', 'module');
return false;
}
});
dictionary.defineTag('deprecated', {
// value is optional
onTagged: function(doclet, tag) {
@ -333,8 +349,12 @@
dictionary.defineTag('requires', {
mustHaveValue: true,
onTagged: function(doclet, tag) {
var modName = firstWordOf(tag.value);
if (modName.indexOf('module:') !== 0) {
modName = 'module:'+modName;
}
if (!doclet.requires) { doclet.requires = []; }
doclet.requires.push( firstWordOf(tag.value) );
doclet.requires.push(modName);
return true;
}

20
test/cases/exportstag.js Normal file
View File

@ -0,0 +1,20 @@
define(function () {
/**
A module representing a shirt.
@exports my/shirt
@version 1.0
*/
var shirt = {
/** A property of the module. */
color: "black",
/** @constructor */
Turtleneck: function(size) {
/** A property of the class. */
this.size = size;
}
};
return shirt;
});

18
test/cases/exportstag2.js Normal file
View File

@ -0,0 +1,18 @@
define(
["my/buttons"],
function () {
/**
A module representing a coat.
@exports my/coat
@requires my/buttons
@version 1.0
*/
var myModule = function(wool) {
/** document me */
this.wool = wool;
}
return myModule;
}
);

3
test/runner.js
View File

@ -95,6 +95,8 @@ testFile('test/t/cases/authortag.js');
testFile('test/t/cases/classtag.js');
testFile('test/t/cases/copyrighttag.js');
testFile('test/t/cases/deprecatedtag.js');
testFile('test/t/cases/exportstag.js');
testFile('test/t/cases/exportstag2.js');
testFile('test/t/cases/exceptiontag.js');
testFile('test/t/cases/globaltag.js');
testFile('test/t/cases/ignoretag.js');
@ -109,5 +111,6 @@ testFile('test/t/cases/sincetag.js');
testFile('test/t/cases/typetag.js');
testFile('test/t/cases/versiontag.js');
report();

27
test/t/cases/exportstag.js Normal file
View File

@ -0,0 +1,27 @@
(function() {
var docSet = testhelpers.getDocSetFromFile('test/cases/exportstag.js'),
shirt = docSet.getByLongname('module:my/shirt')[0],
color = docSet.getByLongname('module:my/shirt.color')[0],
tneck = docSet.getByLongname('module:my/shirt.Turtleneck')[0],
size = docSet.getByLongname('module:my/shirt.Turtleneck#size')[0];
//dump(docSet.doclets); exit(0);
test('When an objlit symbol has an @exports tag, the doclet is aliased to "module:" + the tag value.', function() {
assert.equal(typeof shirt, 'object');
assert.equal(shirt.alias, 'module:my/shirt');
});
test('When an objlit symbol has an @exports tag, the doclet kind is set to module.', function() {
assert.equal(shirt.kind, 'module');
});
test('When an objlit symbol has an @exports tag, the objlit members are documented as members of the module.', function() {
assert.equal(typeof color, 'object');
assert.equal(color.memberof, 'module:my/shirt');
assert.equal(typeof tneck, 'object');
assert.equal(typeof size, 'object');
});
})();

22
test/t/cases/exportstag2.js Normal file
View File

@ -0,0 +1,22 @@
(function() {
var docSet = testhelpers.getDocSetFromFile('test/cases/exportstag2.js'),
coat = docSet.getByLongname('module:my/coat')[0],
wool = docSet.getByLongname('module:my/coat#wool')[0];
//dump(docSet.doclets); exit(0);
test('When a function symbol has an @exports tag, the doclet is aliased to "module:" + the tag value.', function() {
assert.equal(typeof coat, 'object');
assert.equal(coat.alias, 'module:my/coat');
});
test('When a function symbol has an @exports tag, the doclet kind is set to module.', function() {
assert.equal(coat.kind, 'module');
});
test('When a function symbol has an @exports tag, the this members are documented as instance members of the module.', function() {
assert.equal(typeof wool, 'object');
assert.equal(wool.memberof, 'module:my/coat');
});
})();

6
test/t/cases/requirestag.js
View File

@ -5,13 +5,13 @@
//dump(docSet.doclets); exit(0);
test('When a symbol has an @requires tag, the doclet has a requires property that includes that value.', function() {
test('When a symbol has an @requires tag, the doclet has a requires property that includes that value, with the "module:" namespace added.', function() {
assert.equal(typeof foo.requires, 'object');
assert.equal(foo.requires[0], 'module:foo/helper');
assert.equal(typeof bar.requires, 'object');
assert.equal(bar.requires[0], 'foo');
assert.equal(bar.requires[1], 'Pez#blat');
assert.equal(bar.requires[0], 'module:foo');
assert.equal(bar.requires[1], 'module:Pez#blat');
});
})();