From 93d6104d1596be67725a1202054abcadacd0fc6b Mon Sep 17 00:00:00 2001 From: Ryuichi Okumura Date: Fri, 2 Jan 2015 00:09:02 +0900 Subject: [PATCH 1/4] Support @throws tag It works similar with the "@return" tag. This means that a type is optional. An actual example is like the following. And, this resolves #135 finally. /** * @method getName * @throws {Error} Throws an exception error. */ function getName() { // do something } --- docs/syntax/index.mustache | 22 +++++++++++++++++ lib/docparser.js | 30 ++++++++++++++++++++--- tests/input/test/test.js | 11 +++++++++ tests/parser.js | 15 +++++++++++- themes/default/partials/method.handlebars | 19 ++++++++++++++ themes/simple/partials/method.handlebars | 5 ++++ 6 files changed, 98 insertions(+), 4 deletions(-) diff --git a/docs/syntax/index.mustache b/docs/syntax/index.mustache index 7e99d87d..679ba9a7 100644 --- a/docs/syntax/index.mustache +++ b/docs/syntax/index.mustache @@ -165,6 +165,7 @@ toJSON: function () { `@for`, `@param`, `@return`, + `@throws`, `@static`.

@@ -700,6 +701,27 @@ ATTRS[RENDERED] = {

+ + `throws` + +``` +/** + * @method generateClientId + * @throws {Error} An error. + */ +``` + + +

Specifies an error which method throws. + A `@throws` tag has the structure `@throws {type} description`. + The `{type}` is optional.

+

+ See also: + `@method`, + `@return`. +

+ + `for` diff --git a/lib/docparser.js b/lib/docparser.js index b8e705bd..d7cb691d 100644 --- a/lib/docparser.js +++ b/lib/docparser.js @@ -182,6 +182,7 @@ YUI.add('docparser', function (Y) { 'augments': 'uses', // YUI convention for prototype mixins 'depreciated': 'deprecated', // subtle difference 'desciption': 'description', // shouldn't need the @description tag at all + 'exception': 'throws', // we may want standalone inner functions at some point 'extend': 'extends', // typo 'function': 'method', // we may want standalone inner functions at some point 'member': 'method', // probably meant method @@ -191,7 +192,8 @@ YUI.add('docparser', function (Y) { 'parma': 'param', // typo 'propery': 'property', // typo 'prop': 'property', // probably meant property - 'returns': 'return' // need to standardize on one or the other + 'returns': 'return', // need to standardize on one or the other + 'throw': 'throws' // need to standardize on one or the other }, /** @@ -376,7 +378,6 @@ YUI.add('docparser', function (Y) { // @return {type} description // methods // @returns {type} description // methods - // @throws {type} an error #2173342 // @injects {HTML|CSS|script} description // can be used by anthing that has an optional {type} and a description 'return': function (tagname, value, target, block) { @@ -401,7 +402,30 @@ YUI.add('docparser', function (Y) { target[tagname] = result; }, - 'throws': 'return', + + // @throws {type} description + 'throws': function (tagname, value, target) { + var desc = implodeString(trim(value)), + type, + match = REGEX_TYPE.exec(desc), + result; + + if (match) { + type = fixType(trim(match[2])); + desc = trim(match[1] + match[3]); + } + + result = { + description: Y.unindent(explodeString(desc)) + }; + + if (type) { + result.type = type; + } + + target[tagname] = result; + }, + 'injects': 'return', // trying to overwrite the constructor value is a bad idea diff --git a/tests/input/test/test.js b/tests/input/test/test.js index f9cce535..2724440a 100644 --- a/tests/input/test/test.js +++ b/tests/input/test/test.js @@ -47,6 +47,7 @@ * @evil * @injects {HTML} uses a string parameter to populate innerHTML * @returns something without a type + * @throw throw error without a type * @example * This is code * @example @@ -61,6 +62,7 @@ * @param {string} anobject.prop1 prop1 * @param {bool} anobject.prop2 prop2 * @return {string} something with a type + * @throws {error} error with a type */ /** @@ -68,6 +70,7 @@ * @method test0ton * @param {string} [optionalandmultiple]* my desc * @returns something without a type + * @throw throw error without a type */ /** @@ -75,6 +78,7 @@ * @method test1ton * @param {string} multiple* my desc * @returns something without a type + * @throw throw error without a type */ /** @@ -83,6 +87,7 @@ test alternative 1..n param with ...args @method testrestparam1n @param {String} ...multiple my desc @returns something without a type +@throw throw error without a type **/ /** @@ -91,6 +96,7 @@ test alternative 0..n param with ...args @method testrestparam0n @param {String} [...multiple] my desc @returns something without a type +@throw throw error without a type **/ /** @@ -110,6 +116,11 @@ Test newlines before descriptions. Sometimes true, sometimes false. Nobody knows! + +@throws {Error} + Throws an error. + + Catch me. **/ /** diff --git a/tests/parser.js b/tests/parser.js index db5a0ef3..6fe7aa1e 100644 --- a/tests/parser.js +++ b/tests/parser.js @@ -242,6 +242,7 @@ suite.add(new YUITest.TestCase({ 'evil', 'injects', 'return', + 'throws', 'example', 'class', 'module', @@ -254,10 +255,12 @@ suite.add(new YUITest.TestCase({ Assert.areSame('HTML', item.injects.type, 'Injection type not found'); Assert.isUndefined(item["return"].type, 'Type should be missing'); + Assert.isUndefined(item.throws.type, 'Type should be missing'); Assert.areSame(2, item.example.length, 'Should have 2 example snippets'); item2 = this.findByName('testobjectparam', 'myclass'); Assert.areSame('String', item2["return"].type, 'Type should not be missing'); + Assert.areSame('Error', item2.throws.type, 'Type should not be missing'); }, 'test: parameter parsing': function () { var item, item2, item3, item4; @@ -289,6 +292,7 @@ suite.add(new YUITest.TestCase({ Assert.isTrue(item2.params[0].optional, 'Optional not set'); Assert.isTrue(item2.params[0].multiple, 'Multiple not set'); Assert.isUndefined(item2["return"].type, 'Type should be missing'); + Assert.isUndefined(item2.throws.type, 'Type should be missing'); item2 = this.findByName('test1ton', 'myclass'); Assert.isArray(item2.params, 'Params should be an array'); @@ -296,6 +300,7 @@ suite.add(new YUITest.TestCase({ Assert.isUndefined(item2.params[0].optional, 'Optional should not be set'); Assert.isTrue(item2.params[0].multiple, 'Multiple not set'); Assert.isUndefined(item2["return"].type, 'Type should be missing'); + Assert.isUndefined(item2.throws.type, 'Type should be missing'); item3 = this.findByName('testrestparam0n', 'myclass'); Assert.isArray(item3.params, 'Params should be an array'); @@ -303,6 +308,7 @@ suite.add(new YUITest.TestCase({ Assert.isTrue(item3.params[0].optional, 'Optional not set'); Assert.isTrue(item3.params[0].multiple, 'Multiple not set'); Assert.isUndefined(item3['return'].type, 'Type should be missing'); + Assert.isUndefined(item3.throws.type, 'Type should be missing'); item4 = this.findByName('testrestparam1n', 'myclass'); Assert.isArray(item4.params, 'Params should be an array'); @@ -310,6 +316,7 @@ suite.add(new YUITest.TestCase({ Assert.isUndefined(item4.params[0].optional, 'Optional should not be set'); Assert.isTrue(item4.params[0].multiple, 'Multiple not set'); Assert.isUndefined(item4['return'].type, 'Type should be missing'); + Assert.isUndefined(item4.throws.type, 'Type should be missing'); item = this.findByName('testNewlineBeforeDescription', 'myclass'); Assert.isArray(item.params, 'Params should be an array.'); @@ -329,7 +336,7 @@ suite.add(new YUITest.TestCase({ 'Param 1 should have the correct description.' ); }, - 'test: indented return description': function () { + 'test: indented description': function () { var item = this.findByName('testNewlineBeforeDescription', 'myclass'); Assert.areSame('Boolean', item['return'].type, 'Type should be correct.'); @@ -338,6 +345,12 @@ suite.add(new YUITest.TestCase({ item['return'].description, 'Description indentation should be normalized to the first line.' ); + Assert.areSame('Error', item.throws.type, 'Type should be correct.'); + Assert.areSame( + 'Throws an error.\nCatch me.', + item.throws.description, + 'Description indentation should be normalized to the first line.' + ); }, 'test: object parameters': function () { var item, props; diff --git a/themes/default/partials/method.handlebars b/themes/default/partials/method.handlebars index 3a34573f..664d79b1 100644 --- a/themes/default/partials/method.handlebars +++ b/themes/default/partials/method.handlebars @@ -181,6 +181,25 @@ {{/return}} + {{#throws}} +
+

Throws:

+ +
+ {{#if description}} + {{#if type}} + {{#crossLink type}}{{/crossLink}}: + {{/if}} + {{{description}}} + {{else}} + {{#if type}} + {{#crossLink type}}{{/crossLink}}: + {{/if}} + {{/if}} +
+
+ {{/throws}} + {{#example}}

Example:

diff --git a/themes/simple/partials/method.handlebars b/themes/simple/partials/method.handlebars index a24f30ff..8e11dec8 100644 --- a/themes/simple/partials/method.handlebars +++ b/themes/simple/partials/method.handlebars @@ -49,6 +49,11 @@
Returns: {{#if type}}<{{#crossLink type}}{{/crossLink}}> {{/if}}{{{description}}}
{{/return}} {{/if}} + {{#if throws}} + {{#throws}} +
Throws: {{#if type}}<{{#crossLink type}}{{/crossLink}}> {{/if}}{{{description}}}
+ {{/throws}} + {{/if}} {{#if example}}
Example
{{{example}}} From 88cbbe9818426cefdc03ca81f65bba2edb8559cb Mon Sep 17 00:00:00 2001 From: Ryuichi Okumura Date: Fri, 2 Jan 2015 18:16:12 +0900 Subject: [PATCH 2/4] Fix comment for exception as correction --- lib/docparser.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/docparser.js b/lib/docparser.js index d7cb691d..d0bbe6c6 100644 --- a/lib/docparser.js +++ b/lib/docparser.js @@ -182,7 +182,7 @@ YUI.add('docparser', function (Y) { 'augments': 'uses', // YUI convention for prototype mixins 'depreciated': 'deprecated', // subtle difference 'desciption': 'description', // shouldn't need the @description tag at all - 'exception': 'throws', // we may want standalone inner functions at some point + 'exception': 'throws', // need to standardize on one or the other 'extend': 'extends', // typo 'function': 'method', // we may want standalone inner functions at some point 'member': 'method', // probably meant method From 6512ba8b55f82086b3a6c4c357208f3a005c4417 Mon Sep 17 00:00:00 2001 From: Ryuichi Okumura Date: Wed, 14 Jan 2015 21:58:05 +0900 Subject: [PATCH 3/4] Remove "throw" and "exception" tags from scrubbed corrections --- lib/docparser.js | 4 +--- tests/input/test/test.js | 10 +++++----- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/lib/docparser.js b/lib/docparser.js index d0bbe6c6..79d6c3c6 100644 --- a/lib/docparser.js +++ b/lib/docparser.js @@ -182,7 +182,6 @@ YUI.add('docparser', function (Y) { 'augments': 'uses', // YUI convention for prototype mixins 'depreciated': 'deprecated', // subtle difference 'desciption': 'description', // shouldn't need the @description tag at all - 'exception': 'throws', // need to standardize on one or the other 'extend': 'extends', // typo 'function': 'method', // we may want standalone inner functions at some point 'member': 'method', // probably meant method @@ -192,8 +191,7 @@ YUI.add('docparser', function (Y) { 'parma': 'param', // typo 'propery': 'property', // typo 'prop': 'property', // probably meant property - 'returns': 'return', // need to standardize on one or the other - 'throw': 'throws' // need to standardize on one or the other + 'returns': 'return' // need to standardize on one or the other }, /** diff --git a/tests/input/test/test.js b/tests/input/test/test.js index 2724440a..0742cabf 100644 --- a/tests/input/test/test.js +++ b/tests/input/test/test.js @@ -47,7 +47,7 @@ * @evil * @injects {HTML} uses a string parameter to populate innerHTML * @returns something without a type - * @throw throw error without a type + * @throws throw error without a type * @example * This is code * @example @@ -70,7 +70,7 @@ * @method test0ton * @param {string} [optionalandmultiple]* my desc * @returns something without a type - * @throw throw error without a type + * @throws throw error without a type */ /** @@ -78,7 +78,7 @@ * @method test1ton * @param {string} multiple* my desc * @returns something without a type - * @throw throw error without a type + * @throws throw error without a type */ /** @@ -87,7 +87,7 @@ test alternative 1..n param with ...args @method testrestparam1n @param {String} ...multiple my desc @returns something without a type -@throw throw error without a type +@throws throw error without a type **/ /** @@ -96,7 +96,7 @@ test alternative 0..n param with ...args @method testrestparam0n @param {String} [...multiple] my desc @returns something without a type -@throw throw error without a type +@throws throw error without a type **/ /** From 919dea0ab1a92c3a4e92073ef2dc7c30ee519175 Mon Sep 17 00:00:00 2001 From: Ryuichi Okumura Date: Wed, 14 Jan 2015 22:10:21 +0900 Subject: [PATCH 4/4] "throw" tag is the same implementation with "return" tag --- lib/docparser.js | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/lib/docparser.js b/lib/docparser.js index 79d6c3c6..0b4f7d57 100644 --- a/lib/docparser.js +++ b/lib/docparser.js @@ -402,27 +402,7 @@ YUI.add('docparser', function (Y) { }, // @throws {type} description - 'throws': function (tagname, value, target) { - var desc = implodeString(trim(value)), - type, - match = REGEX_TYPE.exec(desc), - result; - - if (match) { - type = fixType(trim(match[2])); - desc = trim(match[1] + match[3]); - } - - result = { - description: Y.unindent(explodeString(desc)) - }; - - if (type) { - result.type = type; - } - - target[tagname] = result; - }, + 'throws': 'return', 'injects': 'return',