From a775ee7c9b1dba5ef4f3c1e45c824dc5526f3dfb Mon Sep 17 00:00:00 2001
From: Greg Cochard <gcochard@users.noreply.github.com>
Date: Fri, 5 Jun 2015 12:43:30 -0700
Subject: [PATCH] Update: Add markers to spaced-comment (fixes #2588)

---
 docs/rules/spaced-comment.md      | 23 +++++++++++++--
 lib/rules/spaced-comment.js       | 48 +++++++++++++++++++++++++++----
 tests/lib/rules/spaced-comment.js | 33 +++++++++++++++++++++
 3 files changed, 96 insertions(+), 8 deletions(-)

diff --git a/docs/rules/spaced-comment.md b/docs/rules/spaced-comment.md
index 4d2b5e3ba329..ea62fd5c1100 100644
--- a/docs/rules/spaced-comment.md
+++ b/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
+```
diff --git a/lib/rules/spaced-comment.js b/lib/rules/spaced-comment.js
index 9c10d29ac978..c43c780fb006 100644
--- a/lib/rules/spaced-comment.js
+++ b/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
diff --git a/tests/lib/rules/spaced-comment.js b/tests/lib/rules/spaced-comment.js
index f7cf2faf4dd4..1c89c537271e 100644
--- a/tests/lib/rules/spaced-comment.js
+++ b/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,