Merge pull request #58 from zxqfox/feature/escape-param-names

Allow ticked param names

Author: qfox

lib/jsdoc.js

@@ -175,13 +175,109 @@ DocLocation.prototype.shift = function(line, column) {
  * @private
  */
 function _parseComment(comment) {
+    var notCleanTagRe = /[^\w\d_]/i;
     var parsed = commentParser(comment, {
         'line_numbers': true,
         'raw_value': true
     })[0];
+
+    if (parsed && Array.isArray(parsed.tags)) {
+        // additional tag.name parsing logic
+        parsed.tags = parsed.tags.map(function(tag) {
+            if (!tag.name || !notCleanTagRe.test(tag.name)) {
+                return tag;
+            }
+
+            var node = _parseNameAgain(tag.name);
+            if (node.error) {
+                tag.error = node.error;
+                return tag;
+            }
+            if (node.ticked) {
+                tag.ticked = node.ticked;
+            }
+            if (node.default) {
+                tag.default = node.default;
+            }
+            if (node.required) {
+                tag.required = node.required;
+            }
+
+            tag.name = node.name;
+
+            return tag;
+        });
+    }
+
     return parsed;
 }
 
+/**
+ * Additional name parsing logic for our purposes
+ * @param {string} str - unparsed name thing
+ * @return {Object}
+ */
+function _parseNameAgain(str) { // (?:\s+(\S+))?
+    var out = {};
+
+    // strip ticks (support for ticked variables)
+    if (str[0] === '`' && str[str.length - 1] === '`') {
+        out.ticked = true;
+        str = str.substr(1, str.length - 2);
+    }
+
+    // strip chevrons
+    if (str[0] === '<' && str[str.length - 1] === '>') {
+        out.required = true;
+        str = str.substr(1, str.length - 2);
+        if (str.replace(/[\s\w\d]+/ig, '') === '') {
+            out.name = str.replace(/^\s+|\s+$/g, '');
+            return out;
+        } else {
+            out.error = 'Unknown name format';
+            return out;
+        }
+    }
+
+    // parsing [name="mix"]
+    var ch;
+    var res = '';
+    var brackets = 0;
+    var re = /\s/;
+    var l = str.length;
+    var pos = 0;
+    while (pos < l) {
+        ch = str[pos];
+        brackets += ch === '[' ? 1 : ch === ']' ? -1 : 0;
+        res += ch;
+        pos ++;
+        if (brackets === 0 && re.test(str[pos])) {
+            break;
+        }
+    }
+    if (brackets) {
+        // throw new Error('Unpaired curly in type doc');
+        out.error = 'Unpaired brackets in type doc';
+        return out;
+    }
+
+    if (res[0] === '[' && res[res.length - 1] === ']') {
+        out.optional = true;
+        res = res.substr(1, res.length - 2);
+        var eqPos = res.indexOf('=');
+        if (eqPos !== -1) {
+            out.name = res.substr(0, eqPos);
+            out.default = res.substr(eqPos + 1).replace(/^(["'])(.+)(\1)$/, '$2');
+        } else {
+            out.name = res;
+        }
+    } else {
+        out.name = res;
+    }
+
+    return out;
+}
+
 /**
  * @param {String} typeString
  * @return {?Array.<SimplifiedType>} - parsed jsdoctype string as array

test/lib/rules/validate-jsdoc/check-param-names.js

@@ -1,4 +1,4 @@
-describe('lib/rules/validate-jsdoc/check-param-names', function () {
+describe('lib/rules/validate-jsdoc/check-param-names', function() {
     var checker = global.checker({
         additionalRules: ['lib/rules/validate-jsdoc.js']
     });
@@ -24,6 +24,7 @@ describe('lib/rules/validate-jsdoc/check-param-names', function () {
 
         checker.cases([
             /* jshint ignore:start */
+            // jscs:disable
             {
                 it: 'should not report',
                 code: function() {
@@ -93,12 +94,14 @@ describe('lib/rules/validate-jsdoc/check-param-names', function () {
                     };
                 }
             }
+            // jscs:enable
             /* jshint ignore:end */
         ]);
 
         // locations
         checker.cases([
             /* jshint ignore:start */
+            // jscs:disable
             {
                 it: 'should report error in jsdoc for function',
                 code: function () {
@@ -123,12 +126,14 @@ describe('lib/rules/validate-jsdoc/check-param-names', function () {
                 },
                 errors: {line: 3, column: 23}
             }
+            // jscs:enable
             /* jshint ignore:end */
         ]);
 
         // out-of-order. issue #33
         checker.cases([
             /* jshint ignore:start */
+            /* jscs:disable */
             {
                 it: 'should report out of order',
                 code: function () {
@@ -206,7 +211,35 @@ describe('lib/rules/validate-jsdoc/check-param-names', function () {
                 errors: [
                     {message: 'expected zzz but got xxx', column: 14, line: 3, rule: "jsDoc"}
                 ]
+
+            }, {
+                it: 'should not report simple ticked param',
+                code: function() {
+                    /**
+                     * @param {String} `message`
+                     */
+                    function methodOne(message) {}
+                }
+            }, {
+                it: 'should not report chevroned params',
+                code: function() {
+                    /**
+                     * @param {String} <required>
+                     * @param {Object} [optional]
+                     */
+                    function methodTwo(required, optional) {}
+                }
+            }, {
+                it: 'should not report ticked params',
+                code: function() {
+                    /**
+                     * @param {String} `<required>`
+                     * @param {Object} `[optional="abcabc"]`
+                     */
+                    function methodThree(required, optional) {}
+                }
             }
+            /* jscs: enable */
             /* jshint ignore:end */
         ]);