Merge branch 'master' into add-more-type-checks-to-valid-types

* master:
  feat(`require-description`): add `descriptionStyle` option to accept implicit descriptions as satisfying the rule by default (fixes #301)
  feat(`match-description`): allow arbitrary tags; also fixes `returns`/`return` to avoid skipping matching of an initial "name" and space

Author: brettz9

.README/rules/match-description.md

@@ -50,6 +50,14 @@ tag should be linted with the `matchDescription` value (or the default).
 }
 ```
 
+The tags `@param`/`@arg`/`@argument` will be properly parsed to ensure that
+the matched "description" text includes only the text after the name.
+All other tags will treat the text following the tag name, a space, and
+an optional curly-bracketed type expression (and another space) as part of
+its "description" (e.g., for `@returns {someType} some description`, the
+description is `some description` while for `@some-tag xyz`, the description
+is `xyz`).
+
 ##### `mainDescription`
 
 If you wish to override the main function description without changing the
@@ -82,6 +90,6 @@ Overrides the default contexts (see below).
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A by default but see `tags` options|
 |Settings||
-|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return', 'description', 'desc'), `mainDescription`, `matchDescription`|
+|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'description', 'desc', and any added to `tags` option, e.g., 'returns', 'return'), `mainDescription`, `matchDescription`|
 
 <!-- assertions matchDescription -->

.README/rules/require-description.md

@@ -2,25 +2,32 @@
 
 Requires that all functions have a description.
 
-* All functions must have a `@description` tag.
-* Every description tag must have a non-empty description that explains the purpose of the method.
+* All functions must have an implicit description or have the option
+  `descriptionStyle` set to `tag`.
+* Every jsdoc block description (or description tag if `descriptionStyle` is
+  `"tag"`) must have a non-empty description that explains the purpose of the
+  method.
 
 #### Options
 
 An options object may have any of the following properties:
 
 - `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 default contexts (see below).
-- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-    block avoids the need for a `@description`. Defaults to an empty array.
+  where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6
+  classes). Overrides the default contexts (see below).
+- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
+    document block avoids the need for a `@description`. Defaults to an
+    empty array.
+- `descriptionStyle` - Whether to accept implicit descriptions (`"body"`) or
+    `@description` tags (`"tag"`) as satisfying the rule. Set to `"any"` to
+    accept either style. Defaults to `"body"`.
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
-|Tags|`description`|
+|Tags|`description` or jsdoc block|
 |Aliases|`desc`|
-|Options|`contexts`, `exemptedBy`|
+|Options|`contexts`, `exemptedBy`, `descriptionStyle`|
 |Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 <!-- assertions requireDescription -->