Merge remote-tracking branch 'upstream/master'

Author: l1bbcsg

.README/README.md

@@ -72,39 +72,50 @@ Add `plugins` section and specify `eslint-plugin-jsdoc` as a plugin.
 
 Finally, enable all of the rules that you would like to use.
 
-```json
+```javascript
 {
     "rules": {
-        "jsdoc/check-alignment": 1,
+        "jsdoc/check-alignment": 1, // Recommended
         "jsdoc/check-examples": 1,
         "jsdoc/check-indentation": 1,
-        "jsdoc/check-param-names": 1,
+        "jsdoc/check-param-names": 1, // Recommended
         "jsdoc/check-syntax": 1,
-        "jsdoc/check-tag-names": 1,
-        "jsdoc/check-types": 1,
-        "jsdoc/implements-on-classes": 1,
+        "jsdoc/check-tag-names": 1, // Recommended
+        "jsdoc/check-types": 1, // Recommended
+        "jsdoc/implements-on-classes": 1, // Recommended
         "jsdoc/match-description": 1,
-        "jsdoc/newline-after-description": 1,
+        "jsdoc/newline-after-description": 1, // Recommended
         "jsdoc/no-types": 1,
-        "jsdoc/no-undefined-types": 1,
+        "jsdoc/no-undefined-types": 1, // Recommended
         "jsdoc/require-description": 1,
         "jsdoc/require-description-complete-sentence": 1,
         "jsdoc/require-example": 1,
         "jsdoc/require-hyphen-before-param-description": 1,
-        "jsdoc/require-jsdoc": 1,
-        "jsdoc/require-param": 1,
-        "jsdoc/require-param-description": 1,
-        "jsdoc/require-param-name": 1,
-        "jsdoc/require-param-type": 1,
-        "jsdoc/require-returns": 1,
-        "jsdoc/require-returns-check": 1,
-        "jsdoc/require-returns-description": 1,
-        "jsdoc/require-returns-type": 1,
-        "jsdoc/valid-types": 1
+        "jsdoc/require-jsdoc": 1, // Recommended
+        "jsdoc/require-param": 1, // Recommended
+        "jsdoc/require-param-description": 1, // Recommended
+        "jsdoc/require-param-name": 1, // Recommended
+        "jsdoc/require-param-type": 1, // Recommended
+        "jsdoc/require-returns": 1, // Recommended
+        "jsdoc/require-returns-check": 1, // Recommended
+        "jsdoc/require-returns-description": 1, // Recommended
+        "jsdoc/require-returns-type": 1, // Recommended
+        "jsdoc/valid-types": 1 // Recommended
     }
 }
 ```
 
+Or you can simply use the following which enables the rules commented
+above as "recommended":
+
+```json
+{
+  "extends": ["plugin:jsdoc/recommended"]
+}
+```
+
+You can then selectively add to or override the recommended rules.
+
 ## Settings
 
 ### Allow `@private` to disable rules for that comment block
@@ -354,7 +365,8 @@ decreasing precedence:
   with JavaScript Markdown lintable by
   [other plugins](https://github.com/eslint/eslint-plugin-markdown), e.g.,
   if one sets `matchingFileName` to `dummy.md` so that `@example` rules will
-  follow one's Markdown rules).
+  follow one's Markdown rules). Note that this option may come at somewhat
+  of a performance penalty as the file's existence is checked by eslint.
 * `settings.jsdoc.configFile` - A config file. Corresponds to ESLint's `-c`.
 * `settings.jsdoc.eslintrcForExamples` - Defaults to `true` in adding rules
   based on an `.eslintrc.*` file. Setting to `false` corresponds to

.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/match-description.md

@@ -6,17 +6,26 @@ The default is this basic expression to match English sentences (Support
 for Unicode upper case may be added in a future version when it can be handled
 by our supported Node versions):
 
-``^([A-Z]|[`\\d_])([\\s\\S]*[.?!`])?$``
+``^([A-Z]|[`\\d_])[\\s\\S]*[.?!`]$``
 
-You can supply your own expression passing a `matchDescription` string on
-the options object.
+#### Options
+
+##### `matchDescription`
+
+You can supply your own expression to override the default, passing a
+`matchDescription` string on the options object.
 
 ```js
 {
   'jsdoc/match-description': ['error', {matchDescription: '[A-Z].*\\.'}]
 }
 ```
 
+As with the default, the supplied regular expression will be applied with the
+Unicode (`"u"`) flag and is *not* case-insensitive.
+
+##### `tags`
+
 If you want different regular expressions to apply to tags, you may use
 the `tags` option object:
 
@@ -41,14 +50,36 @@ tag should be linted with the `matchDescription` value (or the default).
 }
 ```
 
+If you wish to override the main function description without changing the
+default `match-description`, you may use `mainDescription`:
+
+```js
+{
+  'jsdoc/match-description': ['error', {
+    mainDescription: '[A-Z].*\\.',
+    tags: {
+      param: true,
+      returns: true
+    }
+  }]
+}
+```
+
+There is no need to add `mainDescription: true`, as by default, the main
+function (and only the main function) is linted, though you may disable checking
+it by setting it to `false`.
+
+##### `contexts`
 
-By default, only the main function description is linted.
+Set this to an array of strings representing the AST context
+where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
+Overrides the defaults.
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A by default but see `tags` options|
 |Settings||
-|Options|`tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
+|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
 
 <!-- assertions matchDescription -->

.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

@@ -11,7 +11,7 @@ In addition to considering globals found in code (or in ESLint-indicated
 name(path) definitions to also serve as a potential "type" for checking
 the tag types in the table below:
 
-`@callback`, `@class` (or `@constructor`), `@constant` (or `@const`), `@event`, `@external` (or `@host`), `@function` (or `@func` or `@method`), `@interface`, `@member` (or `@var`), `@mixin`, `@name`, `@namespace`, `@template`, `@typedef`.
+`@callback`, `@class` (or `@constructor`), `@constant` (or `@const`), `@event`, `@external` (or `@host`), `@function` (or `@func` or `@method`), `@interface`, `@member` (or `@var`), `@mixin`, `@name`, `@namespace`, `@template` (for Closure/TypeScript), `@typedef`.
 
 The following types are always considered defined.
 
@@ -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-description.md

@@ -9,19 +9,17 @@ Requires that all functions have a description.
 
 An options object may have any of the following properties:
 
-- `contexts` - Set to a string or array of strings representing the AST context
+- `contexts` - Set to an array of strings representing the AST context
   where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
+  Overrides the defaults.
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
     block avoids the need for a `@description`.
-- `noDefaults` - By default, `contexts` will permit `ArrowFunctionExpression`,
-  `FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
-  have `contexts` override these.
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|`description`|
 |Aliases|`desc`|
-|Options|`contexts`, `exemptedBy`, `noDefaults`|
+|Options|`contexts`, `exemptedBy`|
 
 <!-- assertions requireDescription -->