eslint-plugin-jsdoc 43.1.1 → 44.0.0

package/docs/rules/require-returns-type.md

@@ -0,0 +1,181 @@
+<a name="user-content-require-returns-description"></a>
+<a name="require-returns-description"></a>
+# <code>require-returns-description</code>
+
+* [Options](#user-content-require-returns-description-options)
+    * [`contexts`](#user-content-require-returns-description-options-contexts)
+* [Context and settings](#user-content-require-returns-description-context-and-settings)
+* [Failing examples](#user-content-require-returns-description-failing-examples)
+* [Passing examples](#user-content-require-returns-description-passing-examples)
+
+
+Requires that the `@returns` tag has a `description` value. The error
+will not be reported if the return value is `void` or `undefined`
+or if it is `Promise<void>` or `Promise<undefined>`.
+
+<a name="user-content-require-returns-description-options"></a>
+<a name="require-returns-description-options"></a>
+## Options
+
+<a name="user-content-require-returns-description-options-contexts"></a>
+<a name="require-returns-description-options-contexts"></a>
+### <code>contexts</code>
+
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
+Overrides the default contexts (see below). Set to `"any"` if you want
+the rule to apply to any jsdoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., `@callback` or `@function` (or its aliases `@func` or
+`@method`) (including those associated with an `@interface`).
+
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
+section of our README for more on the expected format.
+
+<a name="user-content-require-returns-description-context-and-settings"></a>
+<a name="require-returns-description-context-and-settings"></a>
+## Context and settings
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
+|Tags|`returns`|
+|Aliases|`return`|
+|Recommended|true|
+|Options|`contexts`|
+
+<a name="user-content-require-returns-description-failing-examples"></a>
+<a name="require-returns-description-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````js
+/**
+ * @returns
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @returns description.
+
+/**
+ * @returns {string}
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @returns description.
+
+/**
+ * @returns {string}
+ */
+function quux (foo) {
+
+}
+// "jsdoc/require-returns-description": ["error"|"warn", {"contexts":["any"]}]
+// Message: Missing JSDoc @returns description.
+
+/**
+ * @function
+ * @returns {string}
+ */
+// "jsdoc/require-returns-description": ["error"|"warn", {"contexts":["any"]}]
+// Message: Missing JSDoc @returns description.
+
+/**
+ * @callback
+ * @returns {string}
+ */
+// "jsdoc/require-returns-description": ["error"|"warn", {"contexts":["any"]}]
+// Message: Missing JSDoc @returns description.
+
+/**
+ * @return
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
+// Message: Missing JSDoc @return description.
+
+/**
+ * @returns
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":false}}}
+// Message: Unexpected tag `@returns`
+````
+
+
+
+<a name="user-content-require-returns-description-passing-examples"></a>
+<a name="require-returns-description-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````js
+/**
+ *
+ */
+function quux () {
+
+}
+
+/**
+ * @returns Foo.
+ */
+function quux () {
+
+}
+
+/**
+ * @returns Foo.
+ */
+function quux () {
+
+}
+// "jsdoc/require-returns-description": ["error"|"warn", {"contexts":["any"]}]
+
+/**
+ * @returns {undefined}
+ */
+function quux () {
+
+}
+
+/**
+ * @returns {void}
+ */
+function quux () {
+
+}
+
+/**
+ * @returns {Promise<void>}
+ */
+function quux () {
+
+}
+
+/**
+ * @returns {Promise<undefined>}
+ */
+function quux () {
+
+}
+
+/**
+ * @function
+ * @returns
+ */
+
+/**
+ * @callback
+ * @returns
+ */
+````
+

package/docs/rules/require-returns.md

@@ -0,0 +1,144 @@
+<a name="user-content-require-returns-type"></a>
+<a name="require-returns-type"></a>
+# <code>require-returns-type</code>
+
+* [Options](#user-content-require-returns-type-options)
+    * [`contexts`](#user-content-require-returns-type-options-contexts)
+* [Context and settings](#user-content-require-returns-type-context-and-settings)
+* [Failing examples](#user-content-require-returns-type-failing-examples)
+* [Passing examples](#user-content-require-returns-type-passing-examples)
+
+
+Requires that `@returns` tag has a `type` value (in curly brackets).
+
+<a name="user-content-require-returns-type-options"></a>
+<a name="require-returns-type-options"></a>
+## Options
+
+<a name="user-content-require-returns-type-options-contexts"></a>
+<a name="require-returns-type-options-contexts"></a>
+### <code>contexts</code>
+
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
+Overrides the default contexts (see below). Set to `"any"` if you want
+the rule to apply to any jsdoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., `@callback` or `@function` (or its aliases `@func` or
+`@method`) (including those associated with an `@interface`).
+
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
+section of our README for more on the expected format.
+
+<a name="user-content-require-returns-type-context-and-settings"></a>
+<a name="require-returns-type-context-and-settings"></a>
+## Context and settings
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
+|Tags|`returns`|
+|Aliases|`return`|
+|Recommended|true|
+|Options|`contexts`|
+
+<a name="user-content-require-returns-type-failing-examples"></a>
+<a name="require-returns-type-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````js
+/**
+ * @returns
+ */
+function quux () {
+
+}
+// Message: Missing JSDoc @returns type.
+
+/**
+ * @returns Foo.
+ */
+function quux () {
+
+}
+// Message: Missing JSDoc @returns type.
+
+/**
+ * @returns Foo.
+ */
+function quux () {
+
+}
+// "jsdoc/require-returns-type": ["error"|"warn", {"contexts":["any"]}]
+// Message: Missing JSDoc @returns type.
+
+/**
+ * @function
+ * @returns Foo.
+ */
+// "jsdoc/require-returns-type": ["error"|"warn", {"contexts":["any"]}]
+// Message: Missing JSDoc @returns type.
+
+/**
+ * @callback
+ * @returns Foo.
+ */
+// "jsdoc/require-returns-type": ["error"|"warn", {"contexts":["any"]}]
+// Message: Missing JSDoc @returns type.
+
+/**
+ * @return Foo.
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
+// Message: Missing JSDoc @return type.
+
+/**
+ * @returns
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":false}}}
+// Message: Unexpected tag `@returns`
+````
+
+
+
+<a name="user-content-require-returns-type-passing-examples"></a>
+<a name="require-returns-type-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````js
+/**
+ * @returns {number}
+ */
+function quux () {
+
+}
+
+/**
+ * @returns {number}
+ */
+function quux () {
+
+}
+// "jsdoc/require-returns-type": ["error"|"warn", {"contexts":["any"]}]
+
+/**
+ * @function
+ * @returns Foo.
+ */
+
+/**
+ * @callback
+ * @returns Foo.
+ */
+````
+

package/docs/rules/require-throws.md

@@ -0,0 +1,326 @@
+<a name="user-content-require-throws"></a>
+<a name="require-throws"></a>
+# <code>require-throws</code>
+
+* [Options](#user-content-require-throws-options)
+* [Context and settings](#user-content-require-throws-context-and-settings)
+* [Failing examples](#user-content-require-throws-failing-examples)
+* [Passing examples](#user-content-require-throws-passing-examples)
+
+
+Requires that throw statements are documented.
+
+Note that since throw statements within async functions end up as rejected
+Promises, they are not considered as throw statements for the purposes of this
+rule. See [issue 755](https://github.com/gajus/eslint-plugin-jsdoc/issues/755)
+for our desire for a separate tag to document rejection types and see
+[this discussion](https://stackoverflow.com/questions/50071115/typescript-promise-rejection-type)
+on why TypeScript doesn't offer such a feature.
+
+<a name="user-content-require-throws-options"></a>
+<a name="require-throws-options"></a>
+## Options
+
+- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
+    document block avoids the need for a `@throws`. Defaults to an array
+    with `inheritdoc`. If you set this array, it will overwrite the default,
+    so be sure to add back `inheritdoc` if you wish its presence to cause
+    exemption of the rule.
+- `contexts` - Set this to an array of strings representing the AST context
+    (or an object with `context` and `comment` properties) where you wish
+    the rule to be applied.
+    Overrides the default contexts (see below). Set to `"any"` if you want
+    the rule to apply to any jsdoc block throughout your files (as is necessary
+    for finding function blocks not attached to a function declaration or
+    expression, i.e., `@callback` or `@function` (or its aliases `@func` or
+    `@method`) (including those associated with an `@interface`).
+
+```js
+'jsdoc/require-throws': 'error',
+```
+
+<a name="user-content-require-throws-context-and-settings"></a>
+<a name="require-throws-context-and-settings"></a>
+## Context and settings
+
+| | |
+| -------- | --- |
+| Context  | `ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled |
+| Tags     | `throws` |
+| Aliases  | `exception` |
+|Recommended|true|
+| Options  | `contexts`, `exemptedBy` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+
+<a name="user-content-require-throws-failing-examples"></a>
+<a name="require-throws-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````js
+/**
+ *
+ */
+function quux (foo) {
+  throw new Error('err')
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+const quux = function (foo) {
+  throw new Error('err')
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+const quux = (foo) => {
+  throw new Error('err')
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  while(true) {
+    throw new Error('err')
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  do {
+    throw new Error('err')
+  } while(true)
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  for(var i = 0; i <= 10; i++) {
+    throw new Error('err')
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  for(num in [1,2,3]) {
+    throw new Error('err')
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  for(const num of [1,2,3]) {
+    throw new Error('err')
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  for(const index in [1,2,3]) {
+    throw new Error('err')
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  with(foo) {
+    throw new Error('err')
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  if (true) {
+    throw new Error('err')
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  if (false) {
+    // do nothing
+  } else {
+    throw new Error('err')
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  try {
+    throw new Error('err')
+  } catch(e) {
+    throw new Error(e.message)
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  try {
+    // do nothing
+  } finally {
+    throw new Error(e.message)
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+  const a = 'b'
+  switch(a) {
+    case 'b':
+      throw new Error('err')
+  }
+}
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ * @throws
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"throws":false}}}
+// Message: Unexpected tag `@throws`
+
+/**
+ *
+ */
+const directThrowAfterArrow = (b) => {
+  const a = () => {};
+  if (b) {
+    throw new Error('oops')
+  }
+  return a;
+};
+// Message: Missing JSDoc @throws declaration.
+
+/**
+ * @throws {never}
+ */
+function quux (foo) {
+  throw new Error('err')
+}
+// Message: JSDoc @throws declaration set to "never" but throw value found.
+````
+
+
+
+<a name="user-content-require-throws-passing-examples"></a>
+<a name="require-throws-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````js
+/**
+ * @throws An error.
+ */
+function quux () {
+  throw new Error('err')
+}
+
+/**
+ *
+ */
+function quux (foo) {
+  try {
+    throw new Error('err')
+  } catch(e) {}
+}
+
+/**
+ * @throws {object}
+ */
+function quux (foo) {
+  throw new Error('err')
+}
+
+/**
+ * @inheritdoc
+ */
+function quux (foo) {
+  throw new Error('err')
+}
+
+/**
+ * @abstract
+ */
+function quux (foo) {
+  throw new Error('err')
+}
+
+/**
+ *
+ */
+function quux (foo) {
+}
+
+/**
+ * @type {MyCallback}
+ */
+function quux () {
+  throw new Error('err')
+}
+// "jsdoc/require-throws": ["error"|"warn", {"exemptedBy":["type"]}]
+
+/**
+ *
+ */
+const itself = (n) => n;
+
+/**
+ * Not tracking on nested function
+ */
+const nested = () => () => {throw new Error('oops');};
+
+/**
+ */
+async function foo() {
+  throw Error("bar");
+}
+
+/**
+ * @throws {never}
+ */
+function quux (foo) {
+}
+````
+