diff --git a/modules/jsdoc/tag.js b/modules/jsdoc/tag.js index 421d5172..9ec71f04 100644 --- a/modules/jsdoc/tag.js +++ b/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.} [pname, pdesc, poptional, pdefault]. */ - function parseTagText(tagText) { + function parseParamText(tagText) { var pname, pdesc, poptional, pdefault; // like: pname, pname pdesc, or name - pdesc diff --git a/test/cases/paramtag.js b/test/cases/paramtag.js new file mode 100644 index 00000000..db431bfc --- /dev/null +++ b/test/cases/paramtag.js @@ -0,0 +1,41 @@ +/** +* @param { String | Array} 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) { +} diff --git a/test/cases/typetag.js b/test/cases/typetag.js index 7a617ad0..acaa7cac 100644 --- a/test/cases/typetag.js +++ b/test/cases/typetag.js @@ -5,6 +5,6 @@ var foo; /** - @type number + @type integer */ -var bar; \ No newline at end of file +var bar = +(new Date()).getTime(); \ No newline at end of file diff --git a/test/runner.js b/test/runner.js index 5c1c208e..e3e82595 100644 --- a/test/runner.js +++ b/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'); diff --git a/test/t/cases/paramtag.js b/test/t/cases/paramtag.js new file mode 100644 index 00000000..9a62441a --- /dev/null +++ b/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'); + 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.'); + }); + +})(); \ No newline at end of file diff --git a/test/t/cases/typetag.js b/test/t/cases/typetag.js index 21419aeb..4d0dc9bc 100644 --- a/test/t/cases/typetag.js +++ b/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'); }); })(); \ No newline at end of file