Added feature: if omitting the name of a @param, JSDoc will use the name from the parameter list in the source code.

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": [

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([]);
+        }
     }
 }
 

rhino_modules/jsdoc/src/parser.js

@@ -422,11 +422,8 @@ function aboutNode(node) {
 
         about.type = 'function';
         about.node = node;
-        
-        return about;
     }
-    
+    else if (node.type == Token.VAR || node.type == Token.LET || node.type == Token.CONST) {
-    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;
     }
-     
+    else if (node.type === Token.ASSIGN || node.type === Token.COLON) {
-    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)
+    // get names of the formal parameters declared for this function
-    var string = nodeToString(node);
+    if (about.node && about.node.getParamCount) {
-    if (string) {
+        var paramCount = about.node.getParamCount();
-        about.name = string;
+        if (typeof paramCount === 'number') {
-        return about;
+            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;
 }
 

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) {

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');
+    });
 
 })();