- Fix for matchDescription tags option

- Document `matchDescription`
- Better alphabetize rules

Author: brettz9

.README/README.md

@@ -82,12 +82,14 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/check-syntax": 1,
         "jsdoc/check-tag-names": 1,
         "jsdoc/check-types": 1,
+        "jsdoc/match-description": 1,
         "jsdoc/newline-after-description": 1,
         "jsdoc/no-undefined-types": 1,
         "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,
@@ -310,19 +312,20 @@ Finally, the following rule pertains to inline disable directives:
 {"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/match-description.md"}
 {"gitdown": "include", "file": "./rules/newline-after-description.md"}
 {"gitdown": "include", "file": "./rules/no-undefined-types.md"}
 {"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"}
 {"gitdown": "include", "file": "./rules/require-description.md"}
 {"gitdown": "include", "file": "./rules/require-example.md"}
-{"gitdown": "include", "file": "./rules/require-jsdoc.md"}
 {"gitdown": "include", "file": "./rules/require-hyphen-before-param-description.md"}
+{"gitdown": "include", "file": "./rules/require-jsdoc.md"}
 {"gitdown": "include", "file": "./rules/require-param-description.md"}
 {"gitdown": "include", "file": "./rules/require-param-name.md"}
 {"gitdown": "include", "file": "./rules/require-param-type.md"}
 {"gitdown": "include", "file": "./rules/require-param.md"}
+{"gitdown": "include", "file": "./rules/require-returns-check.md"}
 {"gitdown": "include", "file": "./rules/require-returns-description.md"}
 {"gitdown": "include", "file": "./rules/require-returns-type.md"}
-{"gitdown": "include", "file": "./rules/require-returns-check.md"}
 {"gitdown": "include", "file": "./rules/require-returns.md"}
 {"gitdown": "include", "file": "./rules/valid-types.md"}

.README/rules/match-description.md

@@ -0,0 +1,54 @@
+### `match-description`
+
+Enforces a regular expression pattern on descriptions.
+
+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]*[.?!`])?$``
+
+You can supply your own expression passing a `matchDescription` string on
+the options object.
+
+```js
+{
+  'jsdoc/match-description': ['error', {matchDescription: '[A-Z].*\\.'}]
+}
+```
+
+If you want different regular expressions to apply to tags, you may use
+the `tags` option object:
+
+```js
+{
+  'jsdoc/match-description': ['error', {tags: {
+    param: '\\- [A-Z].*\\.',
+    returns: '[A-Z].*\\.'
+  }}]
+}
+```
+
+In place of a string, you can also add `true` to indicate that a particular
+tag should be linted with the `matchDescription` value (or the default).
+
+```js
+{
+  'jsdoc/match-description': ['error', {tags: {
+    param: true,
+    returns: true
+  }}]
+}
+```
+
+
+By default, only the main function description is linted.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|N/A by default but see `tags` options|
+|Settings||
+|Options|`tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
+
+<!-- assertions matchDescription -->