Merge branch 'master' of github.com:gajus/eslint-plugin-jsdoc

Author: gajus

.README/README.md

@@ -15,8 +15,11 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
 
 | `eslint-plugin-jsdoc` | `jscs-jsdoc` |
 | --- | --- |
+| [`check-alignment`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-alignment) | N/A |
 | [`check-examples`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-examples) | N/A |
+| [`check-indentation`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-indentation) | N/A |
 | [`check-param-names`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-param-names) | [`checkParamNames`](https://github.com/jscs-dev/jscs-jsdoc#checkparamnames) |
+| [`check-syntax`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-syntax) | N/A |
 | [`check-tag-names`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-tag-names) | N/A ~ [`checkAnnotations`](https://github.com/jscs-dev/jscs-jsdoc#checkannotations) |
 | [`check-types`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-types) | [`checkTypes`](https://github.com/jscs-dev/jscs-jsdoc#checktypes) |
 | [`newline-after-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-newline-after-description) | [`requireNewlineAfterDescription`](https://github.com/jscs-dev/jscs-jsdoc#requirenewlineafterdescription) and [`disallowNewlineAfterDescription`](https://github.com/jscs-dev/jscs-jsdoc#disallownewlineafterdescription) |
@@ -72,8 +75,11 @@ Finally, enable all of the rules that you would like to use.
 ```json
 {
     "rules": {
+        "jsdoc/check-alignment": 1,
         "jsdoc/check-examples": 1,
+        "jsdoc/check-indentation": 1,
         "jsdoc/check-param-names": 1,
+        "jsdoc/check-syntax": 1,
         "jsdoc/check-tag-names": 1,
         "jsdoc/check-types": 1,
         "jsdoc/newline-after-description": 1,
@@ -246,8 +252,11 @@ Finally, the following rule pertains to inline disable directives:
 
 ## Rules
 
+{"gitdown": "include", "file": "./rules/check-alignment.md"}
 {"gitdown": "include", "file": "./rules/check-examples.md"}
+{"gitdown": "include", "file": "./rules/check-indentation.md"}
 {"gitdown": "include", "file": "./rules/check-param-names.md"}
+{"gitdown": "include", "file": "./rules/check-syntax.md"}
 {"gitdown": "include", "file": "./rules/check-tag-names.md"}
 {"gitdown": "include", "file": "./rules/check-types.md"}
 {"gitdown": "include", "file": "./rules/newline-after-description.md"}

.README/rules/check-alignment.md

@@ -0,0 +1,10 @@
+### `check-alignment`
+
+Reports invalid alignment of JSDoc block asterisks.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|N/A|
+
+<!-- assertions checkAlignment -->

.README/rules/check-indentation.md

@@ -0,0 +1,10 @@
+### `check-indentation`
+
+Reports invalid padding inside JSDoc block.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|N/A|
+
+<!-- assertions checkIndentation -->

.README/rules/check-syntax.md

@@ -0,0 +1,10 @@
+### `check-syntax`
+
+Reports against Google Closure Compiler syntax.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|N/A|
+
+<!-- assertions checkSyntax -->

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

@@ -8,6 +8,7 @@ Valid [JSDoc 3 Block Tags](http://usejsdoc.org/#block-tags) are:
 abstract
 access
 alias
+async
 augments
 author
 borrows
@@ -28,7 +29,9 @@ external
 file
 fires
 function
+generator
 global
+hideconstructor
 ignore
 implements
 inheritdoc
@@ -41,12 +44,14 @@ license
 listens
 member
 memberof
+memberof!
 mixes
 mixin
 module
 name
 namespace
 override
+package
 param
 private
 property
@@ -67,6 +72,7 @@ type
 typedef
 variation
 version
+yields
 ```
 
 |||

.README/rules/check-types.md

@@ -5,6 +5,8 @@ Reports invalid types.
 Ensures that case of native types is the same as in this list:
 
 ```
+undefined
+null
 boolean
 number
 string
@@ -16,9 +18,9 @@ RegExp
 
 #### Why not capital case everything?
 
-Why are `boolean`, `number` and `string` exempt from starting with a capital letter? Let's take `string` as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as `.toUpperCase()`. 
+Why are `boolean`, `number` and `string` exempt from starting with a capital letter? Let's take `string` as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as `.toUpperCase()`.
 
-Fortunately we don't have to write `new String()` everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the [GC](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) has less work to do. 
+Fortunately we don't have to write `new String()` everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the [GC](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) has less work to do.
 
 So in a sense, there two types of strings in Javascript; `{string}` literals, also called primitives and `{String}` Objects. We use the primitives because it's easier to write and uses less memory. `{String}` and `{string}` are technically both valid, but they are not the same.
 

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

@@ -2,6 +2,8 @@
 
 Requires a hyphen before the `@param` description.
 
+This rule takes one argument. If it is `"always"` then a problem is raised when there is no hyphen before the description. If it is `"never"` then a problem is raised when there is a hyphen before the description. The default value is `"always"`.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|

.README/rules/valid-types.md

@@ -2,6 +2,18 @@
 
 Requires all types to be valid JSDoc or Closure compiler types without syntax errors.
 
+Also impacts behaviors on namepath-pointing or event-pointing tags:
+
+1.  `@alias`, `@augments`, `@extends`, `@lends`, `@memberof`, `@memberof!`, `@mixes`, `@name`, `@this`
+1.  `@callback`, `@event`, `@listens`, `@fires`, `@emits`
+1.  `@borrows`
+
+The following apply to the above sets:
+
+-   Expect tags in set 1 or 2 to have a valid namepath if present
+-   Prevent set 2 from being empty by setting `allowEmptyNamepaths` to `false` as these tags might have some indicative value without a path (but set 1 will always fail if empty)
+-   For the special case of set 3, i.e., `@borrows <that namepath> as <this namepath>`, check that both namepaths are present and valid and ensure there is an `as ` between them.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|