Added test cases for the @param tag.

modules/jsdoc/tag.js

@@ -55,12 +55,15 @@
                 
                 if (remainingText) {
                     if (tagDef.canHaveName) {
-                        var [tagName, tagDesc, tagOptional, tagDefault] = parseTagText(remainingText);
+                        var [paramName, paramDesc, paramOptional, paramDefault]
+                            = parseParamText(remainingText);
                         
-                        if (tagName)     { this.value.name = tagName; }
-                        if (tagDesc)     { this.value.description = tagDesc; }
-                        if (tagOptional) { this.value.optional = tagOptional; }
-                        if (tagDefault)  { this.value.defaultvalue = tagDefault; }
+                        // note the dash is a special case: as a param name it means "no name"
+                        if (paramName && paramName !== '-') { this.value.name = paramName; }
+                        
+                        if (paramDesc)     { this.value.description = paramDesc; }
+                        if (paramOptional) { this.value.optional = paramOptional; }
+                        if (paramDefault)  { this.value.defaultvalue = paramDefault; }
                     }
                     else {
                         this.value.description = remainingText;
@@ -89,11 +92,11 @@
 	/**
 		Parse the parameter name and parameter desc from the tag text.
 		@private
-		@method parseTagText
+		@method parseParamText
 		@param {string} tagText
 		@returns {Array.<string, string, boolean, boolean>} [pname, pdesc, poptional, pdefault].
 	 */
-	function parseTagText(tagText) {
+	function parseParamText(tagText) {
 		var pname, pdesc, poptional, pdefault;
 		
 		// like: pname, pname pdesc, or name - pdesc

test/cases/paramtag.js

@@ -0,0 +1,41 @@
+/**
+*  @param { String | Array<String>}  targetName    The name (or names) of what to find.
+*/
+function find(targetName) {
+}
+
+/**
+*  @param {function} callback
+*/
+function bind(callback) {
+}
+
+/**
+*  @param {function}
+*/
+function unbind(callback) {
+}
+
+/**
+*  @param id The id of the element.
+*/
+function getElement(id) {
+}
+
+/**
+*  @param ... Two or more elements.
+*/
+function combine() {
+}
+
+/**
+*  @param delimiter - What to split on.
+*/
+function split(delimiter) {
+}
+
+/**
+*  @param - If true make the commit atomic.
+*/
+function commit(atomic) {
+}

test/cases/typetag.js

@@ -5,6 +5,6 @@ var foo;
 
 
 /**
-    @type number
+    @type integer
 */
-var bar;
+var bar = +(new Date()).getTime();

test/runner.js

@@ -96,6 +96,7 @@ testFile('test/t/cases/deprecatedtag.js');
 testFile('test/t/cases/exceptiontag.js');
 testFile('test/t/cases/globaltag.js');
 testFile('test/t/cases/ignoretag.js');
+testFile('test/t/cases/paramtag.js');
 testFile('test/t/cases/sincetag.js');
 testFile('test/t/cases/typetag.js');
 testFile('test/t/cases/versiontag.js');

test/t/cases/paramtag.js

@@ -0,0 +1,69 @@
+(function() {
+    var docSet = testhelpers.getDocSetFromFile('test/cases/paramtag.js'),
+        find = docSet.getByLongname('find')[0],
+        unbind = docSet.getByLongname('unbind')[0],
+        bind = docSet.getByLongname('bind')[0],
+        getElement = docSet.getByLongname('getElement')[0],
+        combine = docSet.getByLongname('combine')[0],
+        split = docSet.getByLongname('split')[0],
+        commit = docSet.getByLongname('commit')[0];
+
+    //dump(docSet.doclets); exit(0);
+    
+    test('When a symbol has an @param tag with a type before the name, the doclet has a params property that includes that param.', function() {
+        assert.equal(typeof find.params, 'object');
+        assert.equal(find.params.length, 1);
+        assert.equal(find.params[0].type.names.join(', '), 'String, Array<String>');
+        assert.equal(find.params[0].name, 'targetName');
+        assert.equal(find.params[0].description, 'The name (or names) of what to find.');
+    });
+    
+    test('When a symbol has an @param tag with only a type and name, the doclet has a params property that includes that param.', function() {
+        assert.equal(typeof bind.params, 'object');
+        assert.equal(bind.params.length, 1);
+        assert.equal(bind.params[0].type.names.join(', '), 'function');
+        assert.equal(bind.params[0].name, 'callback');
+        assert.equal(bind.params[0].description, undefined);
+    });
+    
+    test('When a symbol has an @param tag with only a type, the doclet has a params property that includes that param.', function() {
+        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);
+    });
+    
+    test('When a symbol has an @param tag with no type, the doclet has a params property that includes that param.', function() {
+        assert.equal(typeof getElement.params, 'object');
+        assert.equal(getElement.params.length, 1);
+        assert.equal(getElement.params[0].type, undefined);
+        assert.equal(getElement.params[0].name, 'id');
+        assert.equal(getElement.params[0].description, 'The id of the element.');
+    });
+    
+    test('When a symbol has an @param tag with a non-alpha name like "...", the doclet has a params property that includes that param.', function() {
+        assert.equal(typeof combine.params, 'object');
+        assert.equal(combine.params.length, 1);
+        assert.equal(combine.params[0].type, undefined);
+        assert.equal(combine.params[0].name, '...');
+        assert.equal(combine.params[0].description, 'Two or more elements.');
+    });
+    
+    test('When a symbol has an @param tag with name followed by a dash, the doclet has a params property that includes that param.', function() {
+        assert.equal(typeof split.params, 'object');
+        assert.equal(split.params.length, 1);
+        assert.equal(split.params[0].type, undefined);
+        assert.equal(split.params[0].name, 'delimiter');
+        assert.equal(split.params[0].description, 'What to split on.');
+    });
+    
+    test('When a symbol has an @param tag with no name or type, the doclet has a params property that includes that param.', function() {
+        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/t/cases/typetag.js

@@ -12,7 +12,7 @@
     });
     
     test('When a symbol has an @type tag set to a plain string, the doclet has a type property set to that string as if it were a type.', function() {
-        assert.equal(bar.type.names.join(', '), 'number');
+        assert.equal(bar.type.names.join(', '), 'integer');
     });
 
 })();