Merge pull request eslint#2663 from gcochard/fix-2588

Update: Add markers to spaced-comment (fixes eslint#2588)

docs/rules/spaced-comment.md

@@ -13,12 +13,16 @@ This rule takes two arguments. If the first is `"always"` then the `//` or `/*`
 If `"never"` then there should be no whitespace following.
 The default is `"always"`.
 
-The second argument is an object with one key, `"exceptions"`.
-The value is an array of string patterns which are considered exceptions to the rule.
+The second argument is an object with two keys, `"exceptions"` and `"markers"`.
+The `"exceptions"` value is an array of string patterns which are considered exceptions to the rule.
 It is important to note that the exceptions are ignored if the first argument is `"never"`.
 
 Exceptions cannot be mixed. From the collection of exceptions provided only one of them can be used inside the comment. Mixing of more than one is not valid.
 
+The `"markers"` value is an array of string patterns which are considered markers for docblock-style comments,
+such as an additional `/`, used to denote documentation read by doxygen, vsdoc, etc. which must have additional characters.
+The `"markers"` array will apply regardless of the value of the first argument, e.g. `"always"` or `"never"`.
+
 The following patterns are considered warnings:
 
 ```js
@@ -55,6 +59,11 @@ var foo = 5;
 //------++++++++
 ```
 
+```js
+// When ["always",{"markers":["/"]}]
+///This is a comment with a marker but without whitespace
+```
+
 ```js
 // When ["always",{"exceptions":["-","+"]}]
 /*------++++++++*/
@@ -109,3 +118,13 @@ var foo = 5;
 // Comment block
 /*-+-+-+-+-+-+-+*/
 ```
+
+```js
+// When ["always",{"markers":["/"]}]
+/// This is a comment with a marker
+```
+
+```js
+// When ["never",{"markers":["!<"]}]
+//!<This is a comment with a marker
+```

lib/rules/spaced-comment.js

@@ -17,19 +17,38 @@ module.exports = function(context) {
 
     // Default to match anything, so all will fail if there are no exceptions
     var exceptionMatcher = new RegExp(" ");
+    var markerMatcher = new RegExp(" ");
+
+    // Fetch the options dict
+    var hasOptions = context.options.length === 2;
+    var optionsDict = hasOptions ? context.options[1] : {};
 
     // Grab the exceptions array and build a RegExp matcher for it
-    var hasExceptions = context.options.length === 2;
-    var unescapedExceptions = hasExceptions ? context.options[1].exceptions : [];
+    var hasExceptions = hasOptions && optionsDict.exceptions && optionsDict.exceptions.length;
+    var unescapedExceptions = hasExceptions ? optionsDict.exceptions : [];
     var exceptions;
 
-    if (unescapedExceptions.length) {
-        exceptions = unescapedExceptions.map(function(s) {
-            return s.replace(/([.*+?${}()|\^\[\]\/\\])/g, "\\$1");
-        });
+    // Now do the same for markers
+    var hasMarkers = hasOptions && optionsDict.markers && optionsDict.markers.length;
+    var unescapedMarkers = hasMarkers ? optionsDict.markers : [];
+    var markers;
+
+    function escaper(s) {
+        return s.replace(/([.*+?${}()|\^\[\]\/\\])/g, "\\$1");
+    }
+
+    if (hasExceptions) {
+        exceptions = unescapedExceptions.map(escaper);
         exceptionMatcher = new RegExp("(^(" + exceptions.join(")+$)|(^(") + ")+$)");
     }
 
+    if (hasMarkers) {
+        markers = unescapedMarkers.map(escaper);
+
+        // the markerMatcher includes any markers in the list, followed by space/tab
+        markerMatcher = new RegExp("((^(" + markers.join("))|(^(") + ")))[ \\t]");
+    }
+
 
     function checkCommentForSpace(node) {
         var commentIdentifier = node.type === "Block" ? "/*" : "//";
@@ -41,6 +60,11 @@ module.exports = function(context) {
                 return;
             }
 
+            // Check for markers now, and short-circuit if found
+            if (hasMarkers && markerMatcher.test(node.value)) {
+                return;
+            }
+
             // Space expected and not found
             if (node.value.indexOf(" ") !== 0 && node.value.indexOf("\t") !== 0 && node.value.indexOf("\n") !== 0) {
 
@@ -60,6 +84,12 @@ module.exports = function(context) {
             if (node.value.indexOf(" ") === 0 || node.value.indexOf("\t") === 0) {
                 context.report(node, "Unexpected space or tab after " + commentIdentifier + " in comment.");
             }
+            // there won't be a space or tab after commentIdentifier here, but check for the markers and whitespace
+            if (hasMarkers && markerMatcher.test(node.value)) {
+                var matches = node.value.match(markerMatcher), match = matches.length ? matches[0] : "";
+
+                context.report(node, "Unexpected space or tab after marker (" + match + ") in comment.");
+            }
         }
     }
 
@@ -83,6 +113,12 @@ module.exports.schema = [
                 "items": {
                     "type": "string"
                 }
+            },
+            "markers": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
             }
         },
         "additionalProperties": false

tests/lib/rules/spaced-comment.js

@@ -52,6 +52,25 @@ eslintTester.addRuleTest("lib/rules/spaced-comment", {
                 exceptions: ["-", "=", "*", "#", "!@#"]
             }]
         },
+        {
+            code: "//!< docblock style comment",
+            options: ["always", {
+                markers: ["/", "!<"]
+            }]
+        },
+        {
+            code: "//----\n// a comment\n//----\n/// xmldoc style comment\n//!< docblock style comment",
+            options: ["always", {
+                exceptions: ["-"],
+                markers: ["/", "!<"]
+            }]
+        },
+        {
+            code: "///xmldoc style comment",
+            options: ["never", {
+                markers: ["/", "!<"]
+            }]
+        },
         {
             code: validShebangProgram,
             options: ["always"]
@@ -159,6 +178,20 @@ eslintTester.addRuleTest("lib/rules/spaced-comment", {
                 exceptions: ["-", "=", "*", "#", "!@#"]
             }]
         },
+        {
+            code: "//!<docblock style comment",
+            errors: 1,
+            options: ["always", {
+                markers: ["/", "!<"]
+            }]
+        },
+        {
+            code: "//!< docblock style comment",
+            errors: 1,
+            options: ["never", {
+                    markers: ["/", "!<"]
+            }]
+        },
         {
             code: invalidShebangProgram,
             errors: 1,