Merge pull request #298 from golopot/allnodes

BREAKING CHANGE: a subset of rules updated to work on all JSDoc blocks rather than just function-like nodes

Changes apply to check-alignment, check-indentation, check-syntax, check-tag-names, check-types, newline-after-description, require-description-complete-sentence, require-hyphen-before-param-description, valid-types

.README/rules/check-indentation.md

@@ -4,7 +4,7 @@ Reports invalid padding inside JSDoc block.
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|N/A|
 
 <!-- assertions checkIndentation -->

.README/rules/check-syntax.md

@@ -4,7 +4,7 @@ Reports against Google Closure Compiler syntax.
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|N/A|
 
 <!-- assertions checkSyntax -->

.README/rules/check-tag-names.md

@@ -77,7 +77,7 @@ yields
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|N/A|
 |Settings|`tagNamePreference`, `additionalTagNames`|
 

.README/rules/check-types.md

@@ -82,7 +82,7 @@ String | **string** | **string** | `("test") instanceof String` -> **`false`**
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|`class`, `constant`, `enum`, `implements`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `typedef`, `yields`|
 |Aliases|`constructor`, `const`, `var`, `arg`, `argument`, `prop`, `return`, `exception`|
 |Closure-only|`package`, `private`, `protected`, `public`, `static`|

.README/rules/newline-after-description.md

@@ -6,7 +6,7 @@ This rule takes one argument. If it is `"always"` then a problem is raised when
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|N/A|
 
 <!-- assertions newlineAfterDescription -->

.README/rules/no-undefined-types.md

@@ -32,7 +32,7 @@ An option object may have the following keys:
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|`class`, `constant`, `enum`, `implements`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `typedef`, `yields`|
 |Aliases|`constructor`, `const`, `var`, `arg`, `argument`, `prop`, `return`, `exception`, `yield`|
 |Closure-only|`package`, `private`, `protected`, `public`, `static`|

.README/rules/require-description-complete-sentence.md

@@ -9,7 +9,7 @@ Requires that block description and tag description are written in complete sent
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|`param`, `returns`|
 |Aliases|`arg`, `argument`, `return`|
 

.README/rules/require-hyphen-before-param-description.md

@@ -6,7 +6,7 @@ This rule takes one argument. If it is `"always"` then a problem is raised when
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|`param`|
 |Aliases|`arg`, `argument`|
 

.README/rules/valid-types.md

@@ -33,7 +33,7 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags:
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|For name only unless otherwise stated: `alias`, `augments`, `borrows`, `callback`, `class` (for name and type), `constant` (for name and type), `enum` (for type), `event`, `external`, `fires`, `function`, `implements` (for type), `interface`, `lends`, `listens`, `member` (for name and type),  `memberof`, `memberof!`, `mixes`, `mixin`, `module` (for name and type), `name`, `namespace` (for name and type), `param` (for name and type), `property` (for name and type), `returns` (for type), `this`, `throws` (for type), `type` (for type), `typedef` (for name and type), `yields` (for type)|
 |Aliases|`extends`, `constructor`, `const`, `host`, `emits`, `func`, `method`, `var`, `arg`, `argument`, `prop`, `return`, `exception`, `yield`|
 |Closure-only|For type only: `package`, `private`, `protected`, `public`, `static`|

README.md

@@ -511,6 +511,20 @@ function quux (foo) {
 
 }
 // Message: Expected JSDoc block to be aligned.
+
+/**
+  * A jsdoc not attached to any node.
+*/
+// Message: Expected JSDoc block to be aligned.
+
+class Foo {
+  /**
+   *  Some method
+    * @param a
+   */
+  quux(a) {}
+}
+// Message: Expected JSDoc block to be aligned.
 ````
 
 The following patterns are not considered problems:
@@ -537,6 +551,11 @@ function quux (foo) {
 function quux (foo) {
 
 }
+
+/*  <- JSDoc must start with 2 stars.
+  *    So this is unchecked.
+ */
+function quux (foo) {}
 ````
 
 
@@ -788,7 +807,7 @@ Reports invalid padding inside JSDoc block.
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|N/A|
 
 The following patterns are considered problems:
@@ -804,6 +823,13 @@ function quux () {
 
 }
 // Message: There must be no indentation.
+
+/**
+ * Foo
+ *   bar
+ */
+class Moo {}
+// Message: There must be no indentation.
 ````
 
 The following patterns are not considered problems:
@@ -1048,7 +1074,7 @@ Reports against Google Closure Compiler syntax.
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|N/A|
 
 The following patterns are considered problems:
@@ -1162,13 +1188,17 @@ yields
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|N/A|
 |Settings|`tagNamePreference`, `additionalTagNames`|
 
 The following patterns are considered problems:
 
 ````js
+/** @typoo {string} */
+let a;
+// Message: Invalid JSDoc tag name "typoo".
+
 /**
  * @Param
  */
@@ -1443,7 +1473,7 @@ String | **string** | **string** | `("test") instanceof String` -> **`false`**
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|`class`, `constant`, `enum`, `implements`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `typedef`, `yields`|
 |Aliases|`constructor`, `const`, `var`, `arg`, `argument`, `prop`, `return`, `exception`|
 |Closure-only|`package`, `private`, `protected`, `public`, `static`|
@@ -1958,6 +1988,9 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"preferredTypes":{"<>":"[]"}}}
 // Message: Invalid JSDoc @param "foo" type "Array"; prefer: "[]".
+
+/** @typedef {String} foo */
+// Message: Invalid JSDoc @typedef "foo" type "String"; prefer: "string".
 ````
 
 The following patterns are not considered problems:
@@ -2597,7 +2630,7 @@ This rule takes one argument. If it is `"always"` then a problem is raised when
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|N/A|
 
 The following patterns are considered problems:
@@ -2762,7 +2795,7 @@ An option object may have the following keys:
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|`class`, `constant`, `enum`, `implements`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `typedef`, `yields`|
 |Aliases|`constructor`, `const`, `var`, `arg`, `argument`, `prop`, `return`, `exception`, `yield`|
 |Closure-only|`package`, `private`, `protected`, `public`, `static`|
@@ -3050,7 +3083,7 @@ Requires that block description and tag description are written in complete sent
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|`param`, `returns`|
 |Aliases|`arg`, `argument`, `return`|
 
@@ -3632,7 +3665,7 @@ This rule takes one argument. If it is `"always"` then a problem is raised when
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|`param`|
 |Aliases|`arg`, `argument`|
 
@@ -6040,7 +6073,7 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags:
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|For name only unless otherwise stated: `alias`, `augments`, `borrows`, `callback`, `class` (for name and type), `constant` (for name and type), `enum` (for type), `event`, `external`, `fires`, `function`, `implements` (for type), `interface`, `lends`, `listens`, `member` (for name and type),  `memberof`, `memberof!`, `mixes`, `mixin`, `module` (for name and type), `name`, `namespace` (for name and type), `param` (for name and type), `property` (for name and type), `returns` (for type), `this`, `throws` (for type), `type` (for type), `typedef` (for name and type), `yields` (for type)|
 |Aliases|`extends`, `constructor`, `const`, `host`, `emits`, `func`, `method`, `var`, `arg`, `argument`, `prop`, `return`, `exception`, `yield`|
 |Closure-only|For type only: `package`, `private`, `protected`, `public`, `static`|

src/iterateJsdoc.js

@@ -269,16 +269,115 @@ const getSettings = (context) => {
   return settings;
 };
 
-export {
-  parseComment
+/**
+ * Create the report function
+ *
+ * @param {Object} context
+ * @param {Object} commentNode
+ */
+const makeReport = (context, commentNode) => {
+  const report = (message, fix = null, jsdocLoc = null, data = null) => {
+    let loc;
+
+    if (jsdocLoc) {
+      const lineNumber = commentNode.loc.start.line + jsdocLoc.line;
+
+      loc = {
+        end: {line: lineNumber},
+        start: {line: lineNumber}
+      };
+      if (jsdocLoc.column) {
+        const colNumber = commentNode.loc.start.column + jsdocLoc.column;
+
+        loc.end.column = colNumber;
+        loc.start.column = colNumber;
+      }
+    }
+
+    context.report({
+      data,
+      fix,
+      loc,
+      message,
+      node: commentNode
+    });
+  };
+
+  return report;
 };
 
 /**
  * @typedef {ReturnType<typeof getUtils>} Utils
  * @typedef {ReturnType<typeof getSettings>} Settings
+ * @typedef {(
+ *   arg: {
+ *     context: Object,
+ *     sourceCode: Object,
+ *     indent: string,
+ *     jsdoc: Object,
+ *     jsdocNode: Object,
+ *     node: Object | null,
+ *     report: ReturnType<typeof makeReport>,
+ *     settings: Settings,
+ *     utils: Utils,
+ *   }
+ * ) => any } JsdocVisitor
+ */
+
+/**
+ * Create an eslint rule that iterates over all JSDocs, regardless of whether
+ * they are attached to a function-like node.
  *
- * @param {(arg: {utils: Utils, settings: Settings}) => any} iterator
- * @param {{contextDefaults: (true|string[]), meta: any, returns?: any}} ruleConfig
+ * @param {JsdocVisitor} iterator
+ * @param {{meta: any}} ruleConfig
+ */
+const iterateAllJsdocs = (iterator, ruleConfig) => {
+  return {
+    create (context) {
+      return {
+        'Program:exit' () {
+          const comments = context.getSourceCode().getAllComments();
+
+          comments.forEach((comment) => {
+            if (!context.getSourceCode().getText(comment).startsWith('/**')) {
+              return;
+            }
+
+            const indent = _.repeat(' ', comment.loc.start.column);
+            const jsdoc = parseComment(comment, indent);
+            const settings = getSettings(context);
+
+            iterator({
+              context,
+              indent,
+              jsdoc,
+              jsdocNode: comment,
+              node: null,
+              report: makeReport(context, comment),
+              settings: getSettings(context),
+              sourceCode: context.getSourceCode(),
+              utils: getUtils(null, jsdoc, settings, context)
+            });
+          });
+        }
+      };
+    },
+    meta: ruleConfig.meta
+  };
+};
+
+export {
+  parseComment
+};
+
+/**
+ * @param {JsdocVisitor} iterator
+ * @param {{
+ *   meta: any,
+ *   contextDefaults?: true | string[],
+ *   returns?: any,
+ *   iterateAllJsdocs?: true,
+ * }} ruleConfig
  */
 export default function iterateJsdoc (iterator, ruleConfig) {
   const metaType = _.get(ruleConfig, 'meta.type');
@@ -289,6 +388,10 @@ export default function iterateJsdoc (iterator, ruleConfig) {
     throw new TypeError('The iterator argument must be a function or an object with a `returns` method.');
   }
 
+  if (ruleConfig.iterateAllJsdocs) {
+    return iterateAllJsdocs(iterator, {meta: ruleConfig.meta});
+  }
+
   return {
     /**
      * The entrypoint for the JSDoc rule.
@@ -325,32 +428,7 @@ export default function iterateJsdoc (iterator, ruleConfig) {
 
         const jsdoc = parseComment(jsdocNode, indent);
 
-        const report = (message, fix = null, jsdocLoc = null, data = null) => {
-          let loc;
-
-          if (jsdocLoc) {
-            const lineNumber = jsdocNode.loc.start.line + jsdocLoc.line;
-
-            loc = {
-              end: {line: lineNumber},
-              start: {line: lineNumber}
-            };
-            if (jsdocLoc.column) {
-              const colNumber = jsdocNode.loc.start.column + jsdocLoc.column;
-
-              loc.end.column = colNumber;
-              loc.start.column = colNumber;
-            }
-          }
-
-          context.report({
-            data,
-            fix,
-            loc,
-            message,
-            node: jsdocNode
-          });
-        };
+        const report = makeReport(context, jsdocNode);
 
         const utils = getUtils(
           node,