eslint-plugin-jsdoc 3.14.1 → 4.0.1

package/README.md

@@ -23,16 +23,17 @@ JSDoc linting rules for ESLint.
         * [`check-types`](#eslint-plugin-jsdoc-rules-check-types)
         * [`newline-after-description`](#eslint-plugin-jsdoc-rules-newline-after-description)
         * [`no-undefined-types`](#eslint-plugin-jsdoc-rules-no-undefined-types)
-        * [`require-description`](#eslint-plugin-jsdoc-rules-require-description)
         * [`require-description-complete-sentence`](#eslint-plugin-jsdoc-rules-require-description-complete-sentence)
+        * [`require-description`](#eslint-plugin-jsdoc-rules-require-description)
         * [`require-example`](#eslint-plugin-jsdoc-rules-require-example)
         * [`require-hyphen-before-param-description`](#eslint-plugin-jsdoc-rules-require-hyphen-before-param-description)
-        * [`require-param`](#eslint-plugin-jsdoc-rules-require-param)
         * [`require-param-description`](#eslint-plugin-jsdoc-rules-require-param-description)
         * [`require-param-name`](#eslint-plugin-jsdoc-rules-require-param-name)
         * [`require-param-type`](#eslint-plugin-jsdoc-rules-require-param-type)
+        * [`require-param`](#eslint-plugin-jsdoc-rules-require-param)
         * [`require-returns-description`](#eslint-plugin-jsdoc-rules-require-returns-description)
         * [`require-returns-type`](#eslint-plugin-jsdoc-rules-require-returns-type)
+        * [`require-returns`](#eslint-plugin-jsdoc-rules-require-returns)
         * [`valid-types`](#eslint-plugin-jsdoc-rules-valid-types)
 
 
@@ -56,6 +57,7 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
 | [`require-param-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-param-description) | [`requireParamDescription`](https://github.com/jscs-dev/jscs-jsdoc#requireparamdescription) |
 | [`require-param-name`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-param-name) | N/A |
 | [`require-param-type`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-param-type) | [`requireParamTypes`](https://github.com/jscs-dev/jscs-jsdoc#requireparamtypes) |
+| [`require-returns`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns) | [`requireReturn`](https://github.com/jscs-dev/jscs-jsdoc#requirereturn) |
 | [`require-returns-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-description) | [`requireReturnDescription`](https://github.com/jscs-dev/jscs-jsdoc#requirereturndescription) |
 | [`require-returns-type`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-type) | [`requireReturnTypes`](https://github.com/jscs-dev/jscs-jsdoc#requirereturntypes) |
 | [`valid-types`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-valid-types) | N/A |
@@ -114,6 +116,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/require-param-description": 1,
         "jsdoc/require-param-name": 1,
         "jsdoc/require-param-type": 1,
+        "jsdoc/require-returns": 1,
         "jsdoc/require-returns-description": 1,
         "jsdoc/require-returns-type": 1,
         "jsdoc/valid-types": 1
@@ -194,7 +197,7 @@ The format of the configuration is as follows:
 ### Settings to Configure <code>check-examples</code>
 
 The settings below all impact the `check-examples` rule and default to
-no-op/false except for `eslintrcForExamples` which defaults to `true`.
+no-op/false except as noted.
 
 JSDoc specs use of an optional `<caption>` element at the beginning of
 `@example`. The following setting requires its use.
@@ -228,6 +231,9 @@ applied to the JavaScript found within the `@example` tags (as determined
 to be applicable by the above regex settings). They are ordered by
 decreasing precedence:
 
+* `settings.jsdoc.allowInlineConfig` - If not set to `false`, will allow
+  inline config within the `@example` to override other config. Defaults
+  to `true`.
 * `settings.jsdoc.noDefaultExampleRules` - Setting to `true` will disable the
   default rules which are expected to be troublesome for most documentation
   use. See the section below for the specific default rules.
@@ -240,13 +246,20 @@ decreasing precedence:
   [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).
-* `settings.jsdoc.configFile` - A config file. Corresponds to `-c`.
+* `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
-  `--no-eslintrc`.
+  ESLint's `--no-eslintrc`.
 * `settings.jsdoc.baseConfig` - An object of rules with the same schema
   as `.eslintrc.*` for defaults
 
+Finally, the following rule pertains to inline disable directives:
+
+- `settings.jsdoc.reportUnusedDisableDirectives` - If not set to `false`,
+  this will report disabled directives which are not used (and thus not
+  needed). Defaults to `true`. Corresponds to ESLint's
+  `--report-unused-disable-directives`.
+
 <a name="eslint-plugin-jsdoc-settings-settings-to-configure-check-examples-rules-disabled-by-default-unless-nodefaultexamplerules-is-set-to-true"></a>
 #### Rules Disabled by Default Unless <code>noDefaultExampleRules</code> is Set to <code>true</code>
 
@@ -279,11 +292,13 @@ Works in conjunction with the following settings:
 * `captionRequired`
 * `exampleCodeRegex`
 * `rejectExampleCodeRegex`
+* `allowInlineConfig` - Defaults to `true`
 * `noDefaultExampleRules`
 * `matchingFileName`
 * `configFile`
 * `eslintrcForExamples` - Defaults to `true`
 * `baseConfig`
+* `reportUnusedDisableDirectives` - Defaults to `true`
 
 Inline ESLint config within `@example` JavaScript is allowed, though the
 disabling of ESLint directives which are not needed by the resolved rules
@@ -297,7 +312,7 @@ command.
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  * @example alert('hello')
  */
@@ -316,7 +331,7 @@ function quux () {
 
 }
 // Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}}
-// Message: undefined
+// Message: @example error (semi): Extra semicolon.
 
 /**
  * @example
@@ -326,7 +341,7 @@ function quux () {
 
 }
 // Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js ([\\s\\S]*)```"}}
-// Message: undefined
+// Message: @example error (semi): Extra semicolon.
 
 /**
  * @example ```
@@ -336,7 +351,7 @@ function quux () {
 
 }
 // Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```\njs ([\\s\\S]*)```"}}
-// Message: undefined
+// Message: @example error (semi): Extra semicolon.
 
 /**
  * @example <b>Not JavaScript</b>
@@ -351,7 +366,7 @@ function quux2 () {
 
 }
 // Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"rejectExampleCodeRegex":"^\\s*<.*>$"}}
-// Message: undefined
+// Message: @example error (semi): Extra semicolon.
 
 /**
  * @example
@@ -361,7 +376,7 @@ function quux () {
 
 }
 // Settings: {"jsdoc":{"baseConfig":{"rules":{"no-undef":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":true}}
-// Message: undefined
+// Message: @example error (semi): Extra semicolon.
 
 /**
  * @example <caption>Valid usage</caption>
@@ -374,7 +389,7 @@ function quux () {
 
 }
 // Settings: {"jsdoc":{"captionRequired":true,"eslintrcForExamples":false}}
-// Message: undefined
+// Message: Caption is expected for examples.
 
 /**
  * @example  quux();
@@ -383,12 +398,27 @@ function quux () {
 
 }
 // Settings: {"jsdoc":{"baseConfig":{"rules":{"indent":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}}
-// Message: undefined
-```
+// Message: @example error (indent): Expected indentation of 0 spaces but found 1.
+
+/**
+ * @example test() // eslint-disable-line semi
+ */
+function quux () {}
+// Settings: {"jsdoc":{"eslintrcForExamples":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":true}}
+// Message: @example error: Unused eslint-disable directive (no problems were reported from 'semi').
+
+/**
+ * @example
+ test() // eslint-disable-line semi
+ */
+function quux () {}
+// Settings: {"jsdoc":{"allowInlineConfig":false,"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"noDefaultExampleRules":true}}
+// Message: @example error (semi): Missing semicolon.
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * @example ```js
  alert('hello');
@@ -436,7 +466,20 @@ function quux () {
 
 }
 // Settings: {"jsdoc":{"captionRequired":true,"eslintrcForExamples":false}}
-```
+
+/**
+ * @example test() // eslint-disable-line semi
+ */
+function quux () {}
+// Settings: {"jsdoc":{"eslintrcForExamples":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":false}}
+
+/**
+ * @example
+ test() // eslint-disable-line semi
+ */
+function quux () {}
+// Settings: {"jsdoc":{"allowInlineConfig":true,"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"noDefaultExampleRules":true}}
+````
 
 
 <a name="eslint-plugin-jsdoc-rules-check-param-names"></a>
@@ -451,7 +494,7 @@ Ensures that parameter names in JSDoc match those in the function declaration.
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  * @param Foo
  */
@@ -512,11 +555,11 @@ function quux (foo) {
 
 }
 // Message: @param "bar" does not match an existing function parameter.
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  *
  */
@@ -583,7 +626,17 @@ function quux ({a, b} = {}) {
 function quux ([a, b] = []) {
 
 }
-```
+
+/**
+ * Assign the project to a list of employees.
+ * @param {Object[]} employees - The employees who are responsible for the project.
+ * @param {string} employees[].name - The name of an employee.
+ * @param {string} employees[].department - The employee's department.
+ */
+function assign (employees) {
+
+};
+````
 
 
 <a name="eslint-plugin-jsdoc-rules-check-param-names-deconstructing-function-parameter"></a>
@@ -686,7 +739,7 @@ version
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  * @Param
  */
@@ -746,11 +799,11 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
 // Message: Invalid JSDoc tag name "baz".
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * @param foo
  */
@@ -782,7 +835,7 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"additionalTagNames":{"customTags":["baz","bar"]}}}
 
-/**
+/** 
  * @abstract
  * @access
  * @alias
@@ -847,7 +900,7 @@ function quux (foo) {
  * @version
  */
 function quux (foo) {}
-```
+````
 
 
 <a name="eslint-plugin-jsdoc-rules-check-types"></a>
@@ -870,9 +923,9 @@ RegExp
 <a name="eslint-plugin-jsdoc-rules-check-types-why-not-capital-case-everything"></a>
 #### 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.
 
@@ -905,7 +958,7 @@ String | **string** | **string** | `("test") instanceof String` -> **`false`**
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  * @param {Number} foo
  */
@@ -937,11 +990,11 @@ function quux (foo, bar, baz) {
 
 }
 // Message: Invalid JSDoc @param "foo" type "Number".
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * @param {number} foo
  * @param {Bar} bar
@@ -966,7 +1019,7 @@ function quux (foo, bar, baz) {
 function quux (foo, bar, baz) {
 
 }
-```
+````
 
 
 <a name="eslint-plugin-jsdoc-rules-newline-after-description"></a>
@@ -983,7 +1036,7 @@ This rule takes one argument. If it is `"always"` then a problem is raised when
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  * Foo.
  *
@@ -1008,11 +1061,11 @@ function quux () {
 }
 // Options: ["never"]
 // Message: There must be no newline after the description of the JSDoc block.
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * Foo.
  */
@@ -1047,7 +1100,7 @@ function quux () {
 
 }
 // Options: ["never"]
-```
+````
 
 
 <a name="eslint-plugin-jsdoc-rules-no-undefined-types"></a>
@@ -1065,7 +1118,7 @@ When enabling this rule, types in jsdoc comments will resolve as used variables,
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  * @param {strnig} foo - Bar.
  */
@@ -1073,11 +1126,11 @@ function quux(foo) {
 
 }
 // Message: The type 'strnig' is undefined.
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * @param {string} foo - Bar.
  */
@@ -1144,72 +1197,7 @@ function quux(foo) {
 function quux(foo) {
 
 }
-```
-
-
-<a name="eslint-plugin-jsdoc-rules-require-description"></a>
-### <code>require-description</code>
-
-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.
-
-|||
-|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`class`, `example`|
-
-The following patterns are considered problems:
-
-```js
-/**
- *
- */
-function quux () {
-
-}
-// Message: Missing JSDoc @description declaration.
-
-/**
- * @description
- */
-function quux () {
-
-}
-// Message: Missing JSDoc @description description.
-```
-
-The following patterns are not considered problems:
-
-```js
-/**
- * @description
- * // arbitrary description content
- */
-function quux () {
-
-}
-
-/**
- * @description
- * quux(); // does something useful
- */
-function quux () {
-
-}
-
-/**
- * @description <caption>Valid usage</caption>
- * quux(); // does something useful
- *
- * @description <caption>Invalid usage</caption>
- * quux('random unwanted arg'); // results in an error
- */
-function quux () {
-
-}
-```
+````
 
 
 <a name="eslint-plugin-jsdoc-rules-require-description-complete-sentence"></a>
@@ -1229,7 +1217,7 @@ Requires that block description and tag description are written in complete sent
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  * foo.
  */
@@ -1375,11 +1363,11 @@ function quux (foo) {
 
 }
 // Message: Sentence should start with an uppercase character.
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * @param foo - Foo.
  */
@@ -1474,7 +1462,72 @@ function quux () {
 function quux () {
 
 }
-```
+````
+
+
+<a name="eslint-plugin-jsdoc-rules-require-description"></a>
+### <code>require-description</code>
+
+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.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`class`, `example`|
+
+The following patterns are considered problems:
+
+````js
+/**
+ *
+ */
+function quux () {
+
+}
+// Message: Missing JSDoc @description declaration.
+
+/**
+ * @description
+ */
+function quux () {
+
+}
+// Message: Missing JSDoc @description description.
+````
+
+The following patterns are not considered problems:
+
+````js
+/**
+ * @description
+ * // arbitrary description content
+ */
+function quux () {
+
+}
+
+/**
+ * @description
+ * quux(); // does something useful
+ */
+function quux () {
+
+}
+
+/**
+ * @description <caption>Valid usage</caption>
+ * quux(); // does something useful
+ *
+ * @description <caption>Invalid usage</caption>
+ * quux('random unwanted arg'); // results in an error
+ */
+function quux () {
+
+}
+````
 
 
 <a name="eslint-plugin-jsdoc-rules-require-example"></a>
@@ -1492,7 +1545,7 @@ Requires that all functions have examples.
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  *
  */
@@ -1508,11 +1561,11 @@ function quux () {
 
 }
 // Message: Missing JSDoc @example description.
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * @example
  * // arbitrary example content
@@ -1539,7 +1592,7 @@ function quux () {
 function quux () {
 
 }
-```
+````
 
 
 <a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description"></a>
@@ -1554,7 +1607,7 @@ Requires a hyphen before the `@param` description.
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  * @param foo Foo.
  */
@@ -1562,24 +1615,24 @@ function quux () {
 
 }
 // Message: There must be a hyphen before @param description.
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * @param foo - Foo.
  */
 function quux () {
 
 }
-```
+````
 
 
-<a name="eslint-plugin-jsdoc-rules-require-param"></a>
-### <code>require-param</code>
+<a name="eslint-plugin-jsdoc-rules-require-param-description"></a>
+### <code>require-param-description</code>
 
-Requires that all function parameters are documented.
+Requires that `@param` tag has `description` value.
 
 |||
 |---|---|
@@ -1588,81 +1641,234 @@ Requires that all function parameters are documented.
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
- *
+ * @param foo
  */
 function quux (foo) {
 
 }
-// Message: Missing JSDoc @param "foo" declaration.
+// Message: Missing JSDoc @param "foo" description.
 
 /**
- *
+ * @arg foo
  */
 function quux (foo) {
 
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
-// Message: Missing JSDoc @arg "foo" declaration.
+// Message: Missing JSDoc @arg "foo" description.
+````
+
+The following patterns are not considered problems:
 
+````js
 /**
- * @param foo
+ *
  */
-function quux (foo, bar) {
+function quux (foo) {
 
 }
-// Message: Missing JSDoc @param "bar" declaration.
 
 /**
- * @override
+ * @param foo Foo.
  */
 function quux (foo) {
 
 }
-// Message: Missing JSDoc @param "foo" declaration.
+````
+
+
+<a name="eslint-plugin-jsdoc-rules-require-param-name"></a>
+### <code>require-param-name</code>
+
+Requires that all function parameters have name.
+
+> The `@param` tag requires you to specify the name of the parameter you are documenting. You can also include the parameter's type, enclosed in curly brackets, and a description of the parameter.
+>
+> [JSDoc](http://usejsdoc.org/tags-param.html#overview)
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`param`|
+
+The following patterns are considered problems:
 
+````js
 /**
- * @implements
+ * @param
  */
 function quux (foo) {
 
 }
-// Message: Missing JSDoc @param "foo" declaration.
+// Message: There must be an identifier after @param type.
 
 /**
- * @augments
+ * @param {string}
  */
 function quux (foo) {
 
 }
-// Message: Missing JSDoc @param "foo" declaration.
+// Message: There must be an identifier after @param tag.
+````
+
+The following patterns are not considered problems:
 
+````js
 /**
- * @extends
+ * @param foo
  */
 function quux (foo) {
 
 }
-// Message: Missing JSDoc @param "foo" declaration.
 
 /**
- * @override
+ * @param {string} foo
  */
-class A {
-  /**
-    *
-    */
-  quux (foo) {
+function quux (foo) {
 
-  }
 }
-// Message: Missing JSDoc @param "foo" declaration.
+````
 
-/**
- * @implements
- */
-class A {
+
+<a name="eslint-plugin-jsdoc-rules-require-param-type"></a>
+### <code>require-param-type</code>
+
+Requires that `@param` tag has `type` value.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`param`|
+
+The following patterns are considered problems:
+
+````js
+/**
+ * @param foo
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" type.
+
+/**
+ * @arg foo
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
+// Message: Missing JSDoc @arg "foo" type.
+````
+
+The following patterns are not considered problems:
+
+````js
+/**
+ *
+ */
+function quux (foo) {
+
+}
+
+/**
+ * @param {number} foo
+ */
+function quux (foo) {
+
+}
+````
+
+
+<a name="eslint-plugin-jsdoc-rules-require-param"></a>
+### <code>require-param</code>
+
+Requires that all function parameters are documented.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`param`|
+
+The following patterns are considered problems:
+
+````js
+/**
+ *
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
+// Message: Missing JSDoc @arg "foo" declaration.
+
+/**
+ * @param foo
+ */
+function quux (foo, bar) {
+
+}
+// Message: Missing JSDoc @param "bar" declaration.
+
+/**
+ * @override
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @implements
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @augments
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @extends
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @override
+ */
+class A {
+  /**
+    *
+    */
+  quux (foo) {
+
+  }
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @implements
+ */
+class A {
   /**
    *
    */
@@ -1697,11 +1903,11 @@ class A {
   }
 }
 // Message: Missing JSDoc @param "foo" declaration.
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * @param foo
  */
@@ -1887,261 +2093,422 @@ class A {
 
   }
 }
-```
+````
 
 
-<a name="eslint-plugin-jsdoc-rules-require-param-description"></a>
-### <code>require-param-description</code>
+<a name="eslint-plugin-jsdoc-rules-require-returns-description"></a>
+### <code>require-returns-description</code>
 
-Requires that `@param` tag has `description` value.
+Requires that `@returns` tag has `description` value.
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`param`|
+|Tags|`returns`|
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
- * @param foo
+ * @returns
  */
 function quux (foo) {
 
 }
-// Message: Missing JSDoc @param "foo" description.
+// Message: Missing JSDoc @returns description.
 
 /**
- * @arg foo
+ * @return
  */
 function quux (foo) {
 
 }
-// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
-// Message: Missing JSDoc @arg "foo" description.
-```
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
+// Message: Missing JSDoc @return description.
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  *
  */
-function quux (foo) {
+function quux () {
 
 }
 
 /**
- * @param foo Foo.
+ * @returns Foo.
  */
-function quux (foo) {
+function quux () {
 
 }
-```
+````
 
 
-<a name="eslint-plugin-jsdoc-rules-require-param-name"></a>
-### <code>require-param-name</code>
-
-Requires that all function parameters have name.
+<a name="eslint-plugin-jsdoc-rules-require-returns-type"></a>
+### <code>require-returns-type</code>
 
-> The `@param` tag requires you to specify the name of the parameter you are documenting. You can also include the parameter's type, enclosed in curly brackets, and a description of the parameter.
->
-> [JSDoc](http://usejsdoc.org/tags-param.html#overview)
+Requires that `@returns` tag has `type` value.
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`param`|
+|Tags|`returns`|
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
- * @param
+ * @returns
  */
-function quux (foo) {
+function quux () {
 
 }
-// Message: There must be an identifier after @param type.
+// Message: Missing JSDoc @returns type.
 
 /**
- * @param {string}
+ * @returns Foo.
  */
-function quux (foo) {
+function quux () {
 
 }
-// Message: There must be an identifier after @param tag.
-```
-
-The following patterns are not considered problems:
+// Message: Missing JSDoc @returns type.
 
-```js
 /**
- * @param foo
+ * @return Foo.
  */
-function quux (foo) {
+function quux () {
 
 }
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
+// Message: Missing JSDoc @return type.
+````
 
+The following patterns are not considered problems:
+
+````js
 /**
- * @param {string} foo
+ * @returns {number}
  */
-function quux (foo) {
+function quux () {
 
 }
-```
+````
 
 
-<a name="eslint-plugin-jsdoc-rules-require-param-type"></a>
-### <code>require-param-type</code>
+<a name="eslint-plugin-jsdoc-rules-require-returns"></a>
+### <code>require-returns</code>
 
-Requires that `@param` tag has `type` value.
+Requires returns are documented.
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`param`|
+|Tags|`returns`|
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
- * @param foo
+ *
  */
 function quux (foo) {
 
 }
-// Message: Missing JSDoc @param "foo" type.
+// Message: Missing JSDoc @param "foo" declaration.
 
 /**
- * @arg foo
+ *
  */
 function quux (foo) {
 
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
-// Message: Missing JSDoc @arg "foo" type.
-```
+// Message: Missing JSDoc @arg "foo" declaration.
+
+/**
+ * @param foo
+ */
+function quux (foo, bar) {
+
+}
+// Message: Missing JSDoc @param "bar" declaration.
+
+/**
+ * @override
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @implements
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @augments
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @extends
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @override
+ */
+class A {
+  /**
+    *
+    */
+  quux (foo) {
+
+  }
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @implements
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @augments
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @extends
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Message: Missing JSDoc @param "foo" declaration.
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
- *
+ * @param foo
  */
 function quux (foo) {
 
 }
 
 /**
- * @param {number} foo
+ * @inheritdoc
  */
 function quux (foo) {
 
 }
-```
 
+/**
+ * @arg foo
+ */
+function quux (foo) {
 
-<a name="eslint-plugin-jsdoc-rules-require-returns-description"></a>
-### <code>require-returns-description</code>
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
 
-Requires that `@returns` tag has `description` value.
+/**
+ * @override
+ * @param foo
+ */
+function quux (foo) {
 
-|||
-|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`returns`|
+}
 
-The following patterns are considered problems:
+/**
+ * @override
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"allowOverrideWithoutParam":true}}
 
-```js
 /**
- * @returns
+ * @implements
  */
 function quux (foo) {
 
 }
-// Message: Missing JSDoc @returns description.
+// Settings: {"jsdoc":{"allowImplementsWithoutParam":true}}
 
 /**
- * @return
+ * @implements
+ * @param foo
  */
 function quux (foo) {
 
 }
-// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
-// Message: Missing JSDoc @return description.
-```
 
-The following patterns are not considered problems:
+/**
+ * @augments
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}
 
-```js
 /**
- *
+ * @augments
+ * @param foo
  */
-function quux () {
+function quux (foo) {
 
 }
 
 /**
- * @returns Foo.
+ * @extends
  */
-function quux () {
+function quux (foo) {
 
 }
-```
+// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}
 
+/**
+ * @extends
+ * @param foo
+ */
+function quux (foo) {
 
-<a name="eslint-plugin-jsdoc-rules-require-returns-type"></a>
-### <code>require-returns-type</code>
+}
 
-Requires that `@returns` tag has `type` value.
+/**
+ * @override
+ */
+class A {
+  /**
+  * @param foo
+  */
+  quux (foo) {
 
-|||
-|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`returns`|
+  }
+}
 
-The following patterns are considered problems:
+/**
+ * @override
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Settings: {"jsdoc":{"allowOverrideWithoutParam":true}}
 
-```js
 /**
- * @returns
+ * @implements
  */
-function quux () {
+class A {
+  /**
+   *
+   */
+  quux (foo) {
 
+  }
 }
-// Message: Missing JSDoc @returns type.
+// Settings: {"jsdoc":{"allowImplementsWithoutParam":true}}
 
 /**
- * @returns Foo.
+ * @implements
  */
-function quux () {
+class A {
+  /**
+   * @param foo
+   */
+  quux (foo) {
 
+  }
 }
-// Message: Missing JSDoc @returns type.
 
 /**
- * @return Foo.
+ * @augments
  */
-function quux () {
+class A {
+  /**
+   *
+   */
+  quux (foo) {
 
+  }
 }
-// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
-// Message: Missing JSDoc @return type.
-```
+// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}
 
-The following patterns are not considered problems:
+/**
+ * @augments
+ */
+class A {
+  /**
+   * @param foo
+   */
+  quux (foo) {
+
+  }
+}
 
-```js
 /**
- * @returns {number}
+ * @extends
  */
-function quux () {
+class A {
+  /**
+   *
+   */
+  quux (foo) {
 
+  }
 }
-```
+// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}
+
+/**
+ * @extends
+ */
+class A {
+  /**
+   * @param foo
+   */
+  quux (foo) {
+
+  }
+}
+````
 
 
 <a name="eslint-plugin-jsdoc-rules-valid-types"></a>
@@ -2156,7 +2523,7 @@ Requires all types to be valid JSDoc or Closure compiler types without syntax er
 
 The following patterns are considered problems:
 
-```js
+````js
 /**
  * @param {Array<string} foo
  */
@@ -2164,11 +2531,11 @@ function quux() {
 
 }
 // Message: Syntax error in type: Array<string
-```
+````
 
 The following patterns are not considered problems:
 
-```js
+````js
 /**
  * @param {Array<string>} foo
  */
@@ -2189,4 +2556,6 @@ function quux() {
 function quux() {
 
 }
-```
+````
+
+