From 3175288d63c1c4de7b138e904c30f48c7f77fe0f Mon Sep 17 00:00:00 2001 From: Michael Mathews Date: Thu, 20 Oct 2011 23:15:40 +0100 Subject: [PATCH] Added feature: if omitting the name of a @param, JSDoc will use the name from the parameter list in the source code. --- package.json | 2 +- rhino_modules/jsdoc/doclet.js | 12 +++++++ rhino_modules/jsdoc/src/parser.js | 36 +++++++++++-------- .../jsdoc/tag/dictionary/definitions.js | 28 +++++++-------- test/t/cases/paramtag.js | 6 ++-- 5 files changed, 52 insertions(+), 32 deletions(-) diff --git a/package.json b/package.json index 346791cc..7c1d746e 100644 --- a/package.json +++ b/package.json @@ -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": [ diff --git a/rhino_modules/jsdoc/doclet.js b/rhino_modules/jsdoc/doclet.js index e3090134..c324d5ad 100644 --- a/rhino_modules/jsdoc/doclet.js +++ b/rhino_modules/jsdoc/doclet.js @@ -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([]); + } } } diff --git a/rhino_modules/jsdoc/src/parser.js b/rhino_modules/jsdoc/src/parser.js index 23187570..a89c1b84 100644 --- a/rhino_modules/jsdoc/src/parser.js +++ b/rhino_modules/jsdoc/src/parser.js @@ -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,16 +448,28 @@ 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; + } } - // 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; } diff --git a/rhino_modules/jsdoc/tag/dictionary/definitions.js b/rhino_modules/jsdoc/tag/dictionary/definitions.js index 6246c1ee..8f6d33ca 100644 --- a/rhino_modules/jsdoc/tag/dictionary/definitions.js +++ b/rhino_modules/jsdoc/tag/dictionary/definitions.js @@ -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) { diff --git a/test/t/cases/paramtag.js b/test/t/cases/paramtag.js index ada506cc..6f46af94 100644 --- a/test/t/cases/paramtag.js +++ b/test/t/cases/paramtag.js @@ -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'); + }); })(); \ No newline at end of file