eslint-plugin-jsdoc 44.2.3 → 44.2.5

package/docs/rules/require-description-complete-sentence.md

@@ -1,584 +1,820 @@
-<a name="user-content-require-description"></a>
-<a name="require-description"></a>
-# <code>require-description</code>
+<a name="user-content-require-description-complete-sentence"></a>
+<a name="require-description-complete-sentence"></a>
+# <code>require-description-complete-sentence</code>
+
+* [Fixer](#user-content-require-description-complete-sentence-fixer)
+* [Options](#user-content-require-description-complete-sentence-options)
+    * [`tags`](#user-content-require-description-complete-sentence-options-tags)
+    * [`abbreviations`](#user-content-require-description-complete-sentence-options-abbreviations)
+    * [`newlineBeforeCapsAssumesBadSentenceEnd`](#user-content-require-description-complete-sentence-options-newlinebeforecapsassumesbadsentenceend)
+* [Context and settings](#user-content-require-description-complete-sentence-context-and-settings)
+* [Failing examples](#user-content-require-description-complete-sentence-failing-examples)
+* [Passing examples](#user-content-require-description-complete-sentence-passing-examples)
+
+
+Requires that block description, explicit `@description`, and
+`@param`/`@returns` tag descriptions are written in complete sentences, i.e.,
+
+* Description must start with an uppercase alphabetical character.
+* Paragraphs must start with an uppercase alphabetical character.
+* Sentences must end with a period, question mark, exclamation mark, or triple backticks.
+* Every line in a paragraph (except the first) which starts with an uppercase
+  character must be preceded by a line ending with a period.
+* A colon or semi-colon followed by two line breaks is still part of the
+  containing paragraph (unlike normal dual line breaks).
+* Text within inline tags `{...}` or within triple backticks are not checked for sentence divisions.
+* Periods after items within the `abbreviations` option array are not treated
+  as sentence endings.
+
+<a name="user-content-require-description-complete-sentence-fixer"></a>
+<a name="require-description-complete-sentence-fixer"></a>
+## Fixer
+
+If sentences do not end with terminal punctuation, a period will be added.
+
+If sentences do not start with an uppercase character, the initial
+letter will be capitalized.
+
+<a name="user-content-require-description-complete-sentence-options"></a>
+<a name="require-description-complete-sentence-options"></a>
+## Options
+
+<a name="user-content-require-description-complete-sentence-options-tags"></a>
+<a name="require-description-complete-sentence-options-tags"></a>
+### <code>tags</code>
 
-* [Options](#user-content-require-description-options)
-* [Context and settings](#user-content-require-description-context-and-settings)
-* [Failing examples](#user-content-require-description-failing-examples)
-* [Passing examples](#user-content-require-description-passing-examples)
+If you want additional tags to be checked for their descriptions, you may
+add them within this option.
 
+```js
+{
+  'jsdoc/require-description-complete-sentence': ['error', {
+    tags: ['see', 'copyright']
+  }]
+}
+```
 
-Requires that all functions have a description.
+The tags `@param`/`@arg`/`@argument` and `@property`/`@prop` will be properly
+parsed to ensure that the checked "description" text includes only the text
+after the name.
 
-* All functions must have an implicit description (e.g., text above tags) or
-  have the option `descriptionStyle` set to `tag` (requiring `@description`
-  (or `@desc` if that is set as your preferred tag name)).
-* Every jsdoc block description (or `@description` tag if `descriptionStyle`
-  is `"tag"`) must have a non-empty description that explains the purpose of
-  the method.
+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`).
 
-<a name="user-content-require-description-options"></a>
-<a name="require-description-options"></a>
-## Options
+<a name="user-content-require-description-complete-sentence-options-abbreviations"></a>
+<a name="require-description-complete-sentence-options-abbreviations"></a>
+### <code>abbreviations</code>
 
-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).  Set to `"any"` if
-  you want the rule to apply to any jsdoc block throughout your files.
-- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
-    document block avoids the need for a `@description`. 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.
-- `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"`.
-- `checkConstructors` - A value indicating whether `constructor`s should be
-    checked. Defaults to `true`.
-- `checkGetters` - A value indicating whether getters should be checked.
-    Defaults to `true`.
-- `checkSetters` - A value indicating whether setters should be checked.
-    Defaults to `true`.
-
-<a name="user-content-require-description-context-and-settings"></a>
-<a name="require-description-context-and-settings"></a>
+You can provide an `abbreviations` options array to avoid such strings of text
+being treated as sentence endings when followed by dots. The `.` is not
+necessary at the end of the array items.
+
+<a name="user-content-require-description-complete-sentence-options-newlinebeforecapsassumesbadsentenceend"></a>
+<a name="require-description-complete-sentence-options-newlinebeforecapsassumesbadsentenceend"></a>
+### <code>newlineBeforeCapsAssumesBadSentenceEnd</code>
+
+When `false` (the new default), we will not assume capital letters after
+newlines are an incorrect way to end the sentence (they may be proper
+nouns, for example).
+
+<a name="user-content-require-description-complete-sentence-context-and-settings"></a>
+<a name="require-description-complete-sentence-context-and-settings"></a>
 ## Context and settings
 
-| | |
-| -------- | ---------------------- |
-| Context  | `ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled |
-| Tags     | `description` or jsdoc block |
-| Aliases  | `desc` |
-| Recommended | false |
-| Options  | `contexts`, `exemptedBy`, `descriptionStyle`, `checkConstructors`, `checkGetters`, `checkSetters` |
-| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
-
-<a name="user-content-require-description-failing-examples"></a>
-<a name="require-description-failing-examples"></a>
+|||
+|---|---|
+|Context|everywhere|
+|Tags|doc block, `param`, `returns`, `description`, `property`, `summary`, `file`, `classdesc`, `todo`, `deprecated`, `throws`, 'yields' and others added by `tags`|
+|Aliases|`arg`, `argument`, `return`, `desc`, `prop`, `fileoverview`, `overview`, `exception`, `yield`|
+|Recommended|false|
+|Options|`tags`, `abbreviations`, `newlineBeforeCapsAssumesBadSentenceEnd`|
+
+<a name="user-content-require-description-complete-sentence-failing-examples"></a>
+<a name="require-description-complete-sentence-failing-examples"></a>
 ## Failing examples
 
 The following patterns are considered problems:
 
 ````js
 /**
- *
+ * foo.
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// Message: Sentences should start with an uppercase character.
 
 /**
- *
+ * foo?
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"any"}]
-// Message: Missing JSDoc block description or @description declaration.
+// Message: Sentences should start with an uppercase character.
 
 /**
- *
+ * @description foo.
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"body"}]
-// Message: Missing JSDoc block description.
+// Message: Sentences should start with an uppercase character.
 
 /**
- * @desc Not a blank description
+ * Foo)
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"body"}]
-// Message: Remove the @desc tag to leave a plain block description or add additional description text above the @desc line.
+// Message: Sentences must end with a period.
 
 /**
- * @description Not a blank description
+ * `foo` is a variable
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"body"}]
-// Message: Remove the @description tag to leave a plain block description or add additional description text above the @description line.
+// Message: Sentences must end with a period.
 
 /**
+ * Foo.
  *
+ * foo.
  */
-class quux {
+function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"contexts":["ClassDeclaration"],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// Message: Sentences should start with an uppercase character.
 
 /**
- *
+ * тест.
+ */
+function quux () {
+
+}
+// Message: Sentences should start with an uppercase character.
+
+/**
+ * Foo
  */
-class quux {
+function quux () {
 
 }
-// Settings: {"jsdoc":{"contexts":["ClassDeclaration"]}}
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// Message: Sentences must end with a period.
 
 /**
+ * Foo
  *
+ * @param x
  */
-// "jsdoc/require-description": ["error"|"warn", {"contexts":["any"],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+function quux () {
+
+}
+// Message: Sentences must end with a period.
 
 /**
+ * Foo
+ * Bar.
+ */
+function quux () {
+
+}
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"newlineBeforeCapsAssumesBadSentenceEnd":true}]
+// Message: A line of text is started with an uppercase character, but the preceding line does not end the sentence.
+
+/**
+ * Foo.
  *
+ * @param foo foo.
  */
-class quux {
+function quux (foo) {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"contexts":["ClassDeclaration"],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// Message: Sentences should start with an uppercase character.
 
 /**
+ * Foo.
  *
+ * @param foo bar
  */
-class quux {
+function quux (foo) {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"contexts":["ClassDeclaration"],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// Message: Sentences should start with an uppercase character.
 
 /**
- * @description
+ * {@see Foo.bar} buz
  */
-function quux () {
+function quux (foo) {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description description.
+// Message: Sentences should start with an uppercase character.
 
 /**
+ * Foo.
  *
+ * @returns {number} foo
  */
-interface quux {
+function quux (foo) {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"contexts":["TSInterfaceDeclaration"],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// Message: Sentences should start with an uppercase character.
 
 /**
+ * Foo.
  *
+ * @returns foo.
  */
-var quux = class {
+function quux (foo) {
 
-};
-// "jsdoc/require-description": ["error"|"warn", {"contexts":["ClassExpression"],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+}
+// Message: Sentences should start with an uppercase character.
+
+/**
+ * lorem ipsum dolor sit amet, consectetur adipiscing elit. pellentesque elit diam,
+ * iaculis eu dignissim sed, ultrices sed nisi. nulla at ligula auctor, consectetur neque sed,
+ * tincidunt nibh. vivamus sit amet vulputate ligula. vivamus interdum elementum nisl,
+ * vitae rutrum tortor semper ut. morbi porta ante vitae dictum fermentum.
+ * proin ut nulla at quam convallis gravida in id elit. sed dolor mauris, blandit quis ante at,
+ * consequat auctor magna. duis pharetra purus in porttitor mollis.
+ */
+function longDescription (foo) {
+
+}
+// Message: Sentences should start with an uppercase character.
 
 /**
+ * @arg {number} foo - Foo
+ */
+function quux (foo) {
+
+}
+// Message: Sentences must end with a period.
+
+/**
+ * @argument {number} foo - Foo
+ */
+function quux (foo) {
+
+}
+// Message: Sentences must end with a period.
+
+/**
+ * @return {number} foo
+ */
+function quux (foo) {
+
+}
+// Message: Sentences should start with an uppercase character.
+
+/**
+ * Returns bar.
  *
+ * @return {number} bar
  */
-var quux = {
+function quux (foo) {
+
+}
+// Message: Sentences should start with an uppercase character.
 
-};
-// "jsdoc/require-description": ["error"|"warn", {"contexts":["ObjectExpression"],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+/**
+ * @throws {object} Hello World
+ * hello world
+*/
+// Message: Sentences must end with a period.
 
 /**
- * @someDesc
+ * @summary Foo
  */
 function quux () {
 
 }
-// Settings: {"jsdoc":{"tagNamePreference":{"description":{"message":"Please avoid `{{tagName}}`; use `{{replacement}}` instead","replacement":"someDesc"}}}}
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @someDesc description.
+// Message: Sentences must end with a period.
 
 /**
- * @description
+ * @throws {SomeType} Foo
  */
 function quux () {
 
 }
-// Settings: {"jsdoc":{"tagNamePreference":{"description":false}}}
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
-// Message: Unexpected tag `@description`
+// Message: Sentences must end with a period.
 
 /**
- * @description
+ * @see Foo
  */
 function quux () {
 
+}
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["see"]}]
+// Message: Sentences must end with a period.
+
+/**
+ * @param foo Foo bar
+ */
+function quux (foo) {
+
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"description":false}}}
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"any"}]
-// Message: Missing JSDoc block description or @description declaration.
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["param"]}]
+// Message: Sentences must end with a period.
 
 /**
- *
+ * Sorry, but this isn't a complete sentence, Mr.
  */
 function quux () {
-}
-// "jsdoc/require-description": ["error"|"warn", {"exemptedBy":["notPresent"]}]
-// Message: Missing JSDoc block description.
 
-class TestClass {
-  /**
-   *
-   */
-  constructor() { }
 }
-// Message: Missing JSDoc block description.
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
+// Message: Sentences must end with a period.
 
-class TestClass {
-  /**
-   *
-   */
-  constructor() { }
-}
-// "jsdoc/require-description": ["error"|"warn", {"checkConstructors":true}]
-// Message: Missing JSDoc block description.
+/**
+ * Sorry, but this isn't a complete sentence Mr.
+ */
+function quux () {
 
-class TestClass {
-  /**
-   *
-   */
-  get Test() { }
 }
-// Message: Missing JSDoc block description.
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr."]}]
+// Message: Sentences must end with a period.
 
-class TestClass {
-  /**
-   *
-   */
-  get Test() { }
-}
-// "jsdoc/require-description": ["error"|"warn", {"checkGetters":true}]
-// Message: Missing JSDoc block description.
+/**
+ * Sorry, but this isn't a complete sentence Mr. 
+ */
+function quux () {
 
-class TestClass {
-  /**
-   *
-   */
-  set Test(value) { }
 }
-// Message: Missing JSDoc block description.
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
+// Message: Sentences must end with a period.
+
+/**
+ * Sorry, but this isn't a complete sentence Mr. and Mrs.
+ */
+function quux () {
 
-class TestClass {
-  /**
-   *
-   */
-  set Test(value) { }
 }
-// "jsdoc/require-description": ["error"|"warn", {"checkSetters":true}]
-// Message: Missing JSDoc block description.
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr","Mrs"]}]
+// Message: Sentences must end with a period.
 
 /**
- *
+ * This is a complete sentence. But this isn't, Mr.
  */
-class Foo {
-    /**
-     *
-     */
-    constructor() {}
+function quux () {
 
-    /**
-     *
-     */
-    bar() {}
 }
-// "jsdoc/require-description": ["error"|"warn", {"checkConstructors":false,"contexts":["MethodDefinition"]}]
-// Message: Missing JSDoc block description.
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
+// Message: Sentences must end with a period.
 
 /**
- * @implements {Bar}
+ * This is a complete Mr. sentence. But this isn't, Mr.
  */
-class quux {
+function quux () {
 
 }
-// Settings: {"jsdoc":{"implementsReplacesDocs":false}}
-// "jsdoc/require-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTag[rawType=\"Bar\"])","context":"ClassDeclaration"}],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
+// Message: Sentences must end with a period.
 
 /**
- * Has some
- *   description already.
- * @implements {Bar}
+ * This is a complete Mr. sentence.
  */
-class quux {
+function quux () {
 
 }
-// Settings: {"jsdoc":{"implementsReplacesDocs":false}}
-// "jsdoc/require-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTag[rawType=\"Bar\"])","context":"ClassDeclaration"}],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// Message: Sentences should start with an uppercase character.
 
 /**
- * @implements {Bar
- *   | Foo}
+ * This is fun, i.e. enjoyable, but not superlatively so, e.g. not
+ * super, wonderful, etc..
  */
-class quux {
+function quux () {
 
 }
-// Settings: {"jsdoc":{"implementsReplacesDocs":false}}
-// "jsdoc/require-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Bar\"]:nth-child(1))","context":"ClassDeclaration"}],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// Message: Sentences should start with an uppercase character.
 
 /**
- * @implements {Bar}
+ * Do not have dynamic content; e.g. homepage. Here a simple unique id
+ * suffices.
  */
-class quux {
+ function quux () {
+
+ }
+// Message: Sentences should start with an uppercase character.
 
+/**
+ * Implements support for the
+ * Swahili voice synthesizer.
+ */
+function speak() {
 }
-// Settings: {"jsdoc":{"implementsReplacesDocs":false}}
-// "jsdoc/require-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTag[tag=\"implements\"])","context":"ClassDeclaration"}],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"newlineBeforeCapsAssumesBadSentenceEnd":true}]
+// Message: A line of text is started with an uppercase character, but the preceding line does not end the sentence.
 
 /**
- * @implements {Bar}
+ * Foo.
+ *
+ * @template TempA, TempB foo.
  */
-class quux {
+function quux (foo) {
 
 }
-// Settings: {"jsdoc":{"implementsReplacesDocs":false}}
-// "jsdoc/require-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTag[tag=\"implements\"])","context":"any"}],"descriptionStyle":"tag"}]
-// Message: Missing JSDoc @description declaration.
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["template"]}]
+// Message: Sentences should start with an uppercase character.
+
+/**
+ * Just a component.
+ * @param {Object} props Свойства.
+ * @return {ReactElement}.
+ */
+function quux () {}
+// Message: Sentences must be more than punctuation.
 ````
 
 
 
-<a name="user-content-require-description-passing-examples"></a>
-<a name="require-description-passing-examples"></a>
+<a name="user-content-require-description-complete-sentence-passing-examples"></a>
+<a name="require-description-complete-sentence-passing-examples"></a>
 ## Passing examples
 
 The following patterns are not considered problems:
 
 ````js
 /**
- *
+ * @param foo - Foo.
  */
+function quux () {
+
+}
 
 /**
- * @description
- * // arbitrary description content
+ * Foo.
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
 
 /**
- * @description
- * quux(); // does something useful
+ * Foo.
+ * Bar.
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
 
 /**
- * @description <caption>Valid usage</caption>
- * quux(); // does something useful
+ * Foo.
  *
- * @description <caption>Invalid usage</caption>
- * quux('random unwanted arg'); // results in an error
+ * Bar.
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
 
 /**
- *
+ * Тест.
  */
-class quux {
+function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
 
 /**
- *
+ * Foo
+ * bar.
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"contexts":["ClassDeclaration"]}]
 
 /**
- * @type {MyCallback}
+ * @returns Foo bar.
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"exemptedBy":["type"]}]
 
 /**
+ * Foo {@see Math.sin}.
+ */
+function quux () {
+
+}
+
+/**
+ * Foo {@see Math.sin} bar.
+ */
+function quux () {
+
+}
+
+/**
+ * Foo?
  *
+ * Bar!
+ *
+ * Baz:
+ *   1. Foo.
+ *   2. Bar.
+ */
+function quux () {
+
+}
+
+/**
+ * Hello:
+ * World.
  */
-interface quux {
+function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
 
-interface quux {
-  /**
-   * If the thing should be checked.
-   */
-  checked?: boolean
+/**
+ * Hello: world.
+ */
+function quux () {
+
 }
-// "jsdoc/require-description": ["error"|"warn", {"contexts":["TSPropertySignature"]}]
 
 /**
  *
  */
-var quux = class {
+function quux () {
+
+}
+
+/**
+ * @description Foo.
+ */
+function quux () {
 
-};
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
+}
 
 /**
+ * `foo` is a variable.
+ */
+function quux () {
+
+}
+
+/**
+ * Foo.
  *
+ * `foo`.
+ */
+function quux () {
+
+}
+
+/**
+ * @param foo - `bar`.
  */
-var quux = {
+function quux () {
 
-};
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
+}
 
 /**
- * Has an implicit description
+ * @returns {number} `foo`.
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"body"}]
 
 /**
- * Has an implicit description
+ * Foo
+ * `bar`.
  */
 function quux () {
 
 }
 
 /**
- * Has an implicit description
+ * @example Foo
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"any"}]
 
 /**
- * @description Has an explicit description
+ * @see Foo
  */
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"any"}]
 
 /**
+ * Foo.
  *
+ * @param foo Foo.
  */
-function quux () {
+function quux (foo) {
+
+}
+
+/**
+ * Foo.
+ *
+ * @param foo Foo.
+ */
+function quux (foo) {
+
+}
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["param"]}]
+
+/**
+ * @param foo Foo bar.
+ */
+function quux (foo) {
 
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"description":false}}}
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["param"]}]
+
+/**
+ *
+ */
+function quux (foo) {
 
-class TestClass {
-  /**
-   * Test.
-   */
-  constructor() { }
 }
+// Settings: {"jsdoc":{"tagNamePreference":{"description":false}}}
+
+/**
+* We stop loading Items when we have loaded:
+*
+* 1) The main Item;
+* 2) All its variants.
+*/
+
+/**
+ * This method is working on 2 steps.
+ *
+ * | Step | Comment     |
+ * |------|-------------|
+ * |   1  | do it       |
+ * |   2  | do it again |
+ */
+
+/**
+ * This is something that
+ * I want to test.
+ */
+function quux () {
 
-class TestClass {
-  /**
-   *
-   */
-  constructor() { }
 }
-// "jsdoc/require-description": ["error"|"warn", {"checkConstructors":false}]
 
-class TestClass {
-  /**
-   * Test.
-   */
-  get Test() { }
+/**
+ * When making HTTP requests, the
+ * URL is super important.
+ */
+function quux () {
+
 }
 
-class TestClass {
-  /**
-   *
-   */
-  get Test() { }
+/**
+ * Sorry, but this isn't a complete sentence, Mr.
+ */
+function quux () {
+
 }
-// "jsdoc/require-description": ["error"|"warn", {"checkGetters":false}]
 
-class TestClass {
-  /**
-   * Test.
-   */
-  set Test(value) { }
+/**
+ * Sorry, but this isn't a complete sentence Mr..
+ */
+function quux () {
+
+}
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr."]}]
+
+/**
+ * Sorry, but this isn't a complete sentence Mr. 
+ */
+function quux () {
+
 }
 
-class TestClass {
-  /**
-   *
-   */
-  set Test(value) { }
+/**
+ * Sorry, but this isn't a complete sentence Mr. and Mrs..
+ */
+function quux () {
+
+}
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr","Mrs"]}]
+
+/**
+ * This is a complete sentence aMr.
+ */
+function quux () {
+
+}
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
+
+/**
+ * This is a complete sentence. But this isn't, Mr.
+ */
+function quux () {
+
+}
+
+/**
+ * This is a complete Mr. Sentence. But this isn't, Mr.
+ */
+function quux () {
+
 }
-// "jsdoc/require-description": ["error"|"warn", {"checkSetters":false}]
 
 /**
- * Multi
- * line
+ * This is a complete Mr. sentence.
  */
 function quux () {
 
 }
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
 
-/** Single line */
+/**
+ * This is fun, i.e. enjoyable, but not superlatively so, e.g. not
+ * super, wonderful, etc..
+ */
 function quux () {
 
 }
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["etc","e.g.","i.e."]}]
+
 
-/** @description something */
+**
+* Do not have dynamic content; e.g. homepage. Here a simple unique id
+* suffices.
+*/
 function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"descriptionStyle":"tag"}]
+// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["etc","e.g.","i.e."]}]
 
 /**
- * @implements {Bar}
+ * Implements support for the
+ * Swahili voice synthesizer.
  */
-class quux {
+function speak() {
+}
 
+/**
+ * @param foo
+ *
+ * @returns {void}
+ */
+export default (foo) => {
+  foo()
 }
-// Settings: {"jsdoc":{"implementsReplacesDocs":false}}
-// "jsdoc/require-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=/\\s{4}/]:has(JsdocTag[rawType=\"class\"])","context":"ClassDeclaration"}],"descriptionStyle":"tag"}]
+
+/** @file To learn more,
+ * see: https://github.com/d3/d3-ease. */
+
+/** To learn more,
+ * see: https://github.com/d3/d3-ease. */
 
 /**
- * Has some
- *   description already.
+ * This is a complete sentence...
  */
-class quux {
+function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTag[rawType=\"{Bar}\"])","context":"ClassDeclaration"}],"descriptionStyle":"tag"}]
 
 /**
- * Has some
- *   description already.
+ * He wanted a few items: a jacket and shirt...
  */
-class quux {
+function quux () {
 
 }
-// "jsdoc/require-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTag[rawType=\"{Bar}\"])","context":"any"}],"descriptionStyle":"tag"}]
 
 /**
- * Has some
- *   description already.
+ * The code in question was...
+ * ```
+ * alert('hello');
+ * ```
  */
-// "jsdoc/require-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTag[rawType=\"{Bar}\"])","context":"any"}],"descriptionStyle":"tag"}]
+function quux () {
+
+}
+
+/**
+ * @param {number|string|Date|Object|OverType|WhateverElse} multiType -
+ * Nice long explanation...
+ */
+function test (multiType) {
+}
+
+/**
+ * Any kind of fowl (e.g., a duck).
+ */
+function quux () {}
+
+/**
+ * The code in question was...
+ * ```
+ * do something
+ *
+ * interesting
+ * ```
+ */
+function quux () {
+
+}
 ````