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 feature: if omitting the name of a @param, JSDoc will use the name from the parameter list in the source code.

Browse Source
This commit is contained in:
Michael Mathews 2011-10-20 23:15:40 +01:00
parent ab9d00186c
commit 3175288d63
5 changed files with 52 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
package.json
View File

@ -1,7 +1,7 @@
{
"name": "JSDoc",
"version": "3.0.0alpha",
"revision": "1318707954271",
"revision": "1319148880850",
"description": "An automatic documentation generator for javascript.",
"keywords": [ "documentation", "javascript" ],
"licenses": [

12
rhino_modules/jsdoc/doclet.js
View File

@ -61,6 +61,15 @@ exports.Doclet.prototype.postProcess = function() {
if (this.variation && this.longname && !/\)$/.test(this.longname) ) {
this.longname += '('+this.variation+')';
}
// add in any missing param names
if (this.params && this.meta && this.meta.code && this.meta.code.paramnames) {
for (var i = 0, len = this.params.length; i < len; i++) {
if (!this.params[i].name) {
this.params[i].name = this.meta.code.paramnames[i] || '';
}
}
}
}
/** Add a tag to this doclet.
@ -208,6 +217,9 @@ exports.Doclet.prototype.setMeta = function(meta) {
/** The value of the symbol in the source code. */
this.meta.code.value = meta.code.value;
}
if (meta.code.paramnames) {
this.meta.code.paramnames = meta.code.paramnames.concat([]);
}
}
}

28
rhino_modules/jsdoc/src/parser.js
View File

@ -422,11 +422,8 @@ function aboutNode(node) {
about.type = 'function';
about.node = node;
return about;
}
if (node.type == Token.VAR || node.type == Token.LET || node.type == Token.CONST) {
else if (node.type == Token.VAR || node.type == Token.LET || node.type == Token.CONST) {
about.name = nodeToString(node.target);
if (node.initializer) { // like var i = 0;
about.node = node.initializer;
@ -438,11 +435,8 @@ function aboutNode(node) {
about.value = nodeToString(about.node);
about.type = 'undefined';
}
return about;
}
if (node.type === Token.ASSIGN || node.type === Token.COLON) {
else if (node.type === Token.ASSIGN || node.type === Token.COLON) {
about.name = nodeToString(node.left);
if (node.type === Token.COLON) {
@ -454,14 +448,26 @@ function aboutNode(node) {
about.node = node.right;
about.value = nodeToString(about.node);
about.type = getTypeName(node.right);
return about;
}
else {
// type 39 (NAME)
var string = nodeToString(node);
if (string) {
about.name = string;
return about;
}
}
// get names of the formal parameters declared for this function
if (about.node && about.node.getParamCount) {
var paramCount = about.node.getParamCount();
if (typeof paramCount === 'number') {
about.node.flattenSymbolTable(true);
var paramNames = [];
for (var i = 0, len = paramCount; i < len; i++) {
paramNames.push(''+about.node.getParamOrVarName(i));
}
about.paramnames = paramNames;
}
}
return about;

28
rhino_modules/jsdoc/tag/dictionary/definitions.js
View File

@ -298,6 +298,18 @@ exports.defineTags = function(dictionary) {
}
});
dictionary.defineTag('member', {
canHaveType: true,
onTagged: function(doclet, tag) {
setDocletKindToTitle(doclet, tag);
setDocletNameToValue(doclet, tag);
if (tag.value && tag.value.type) {
doclet.type = tag.value.type;
}
}
})
.synonym('var');
dictionary.defineTag('memberof', {
mustHaveValue: true,
onTagged: function(doclet, tag) {
@ -349,12 +361,12 @@ exports.defineTags = function(dictionary) {
});
dictionary.defineTag('param', {
mustHaveValue: true,
//mustHaveValue: true, // param name can be found in the source code if not provided
canHaveType: true,
canHaveName: true,
onTagged: function(doclet, tag) {
if (!doclet.params) { doclet.params = []; }
doclet.params.push(tag.value);
doclet.params.push(tag.value||{});
}
})
.synonym('argument')
@ -377,18 +389,6 @@ exports.defineTags = function(dictionary) {
})
.synonym('prop');
dictionary.defineTag('member', {
canHaveType: true,
onTagged: function(doclet, tag) {
setDocletKindToTitle(doclet, tag);
setDocletNameToValue(doclet, tag);
if (tag.value && tag.value.type) {
doclet.type = tag.value.type;
}
}
})
.synonym('var');
dictionary.defineTag('protected', {
mustNotHaveValue: true,
onTagged: function(doclet, tag) {

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

@ -28,7 +28,6 @@
assert.equal(typeof unbind.params, 'object');
assert.equal(unbind.params.length, 1);
assert.equal(unbind.params[0].type.names.join(', '), 'function');
assert.equal(unbind.params[0].name, undefined);
assert.equal(unbind.params[0].description, undefined);
});
@ -60,8 +59,11 @@
assert.equal(typeof commit.params, 'object');
assert.equal(commit.params.length, 1);
assert.equal(commit.params[0].type, undefined);
assert.equal(commit.params[0].name, undefined);
assert.equal(commit.params[0].description, 'If true make the commit atomic.');
});
test('When a symbol has an @param tag with no name and a name is given in the code, the doclet has a params property that includes that param with the name from the code.', function() {
assert.equal(commit.params[0].name, 'atomic');
});
})();