docs: generate docs

README.md

@@ -491,7 +491,7 @@ syntax highlighting). The following options determine whether a given
   so you may wish to use `(?:...)` groups where you do not wish the
   first such group treated as one to include. If no parenthetical group
   exists or matches, the whole matching expression will be used.
-  An example might be ````"^```(?:js|javascript)([\\s\\S]*)```$"````
+  An example might be ````"^```(?:js|javascript)([\\s\\S]*)```\s*$"````
   to only match explicitly fenced JavaScript blocks.
 * `rejectExampleCodeRegex` - Regex blacklist which rejects
   non-lintable examples (has priority over `exampleCodeRegex`). An example
@@ -502,6 +502,25 @@ If neither is in use, all examples will be matched. Note also that even if
 `captionRequired` is not set, any initial `<caption>` will be stripped out
 before doing the regex matching.
 
+<a name="eslint-plugin-jsdoc-rules-options-paddedindent"></a>
+#### <code>paddedIndent</code>
+
+This integer property allows one to add a fixed amount of whitespace at the
+beginning of the second or later lines of the example to be stripped so as
+to avoid linting issues with the decorative whitespace. For example, if set
+to a value of `4`, the initial whitespace below will not trigger `indent`
+rule errors as the extra 4 spaces on each subsequent line will be stripped
+out before evaluation.
+
+```js
+/**
+ * @example
+ *     anArray.filter((a) => {
+ *      return a.b;
+ *     });
+ */
+```
+
 <a name="eslint-plugin-jsdoc-rules-options-reportunuseddisabledirectives"></a>
 #### <code>reportUnusedDisableDirectives</code>
 
@@ -604,6 +623,7 @@ function quux () {
 
 /**
  * @example
+ *
  * ```js alert('hello'); ```
  */
 function quux () {
@@ -644,7 +664,7 @@ function quux () {
 function quux2 () {
 
 }
-// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"rejectExampleCodeRegex":"^\\s*<.*>$"}]
+// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"rejectExampleCodeRegex":"^\\s*<.*>\\s*$"}]
 // Message: @example error (semi): Extra semicolon.
 
 /**
@@ -696,7 +716,7 @@ function quux () {}
 
 /**
  * @example const i = 5;
- *          quux2()
+ * quux2()
  */
 function quux2 () {
 
@@ -706,7 +726,18 @@ function quux2 () {
 
 /**
  * @example const i = 5;
- *          quux2()
+ *   quux2()
+ */
+function quux2 () {
+
+}
+// Options: [{"paddedIndent":2}]
+// Message: @example warning (id-length): Identifier name 'i' is too short (< 2).
+
+/**
+ * @example
+ * const i = 5;
+ * quux2()
  */
 function quux2 () {
 
@@ -715,7 +746,7 @@ function quux2 () {
 
 /**
  * @example const i = 5;
- *          quux2()
+ * quux2()
  */
 function quux2 () {
 
@@ -825,6 +856,15 @@ var quux = {
 
 };
 // Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}]
+
+/**
+ * @example
+ * foo(function (err) {
+ *     throw err;
+ * });
+ */
+function quux () {}
+// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}]
 ````
 
 
@@ -3139,6 +3179,23 @@ function quux () {
 }
 // Options: ["never"]
 // Message: There must be no newline after the description of the JSDoc block.
+
+/**
+* A.
+*
+* @typedef {Object} A
+* @prop {boolean} a A.
+*/
+// Options: ["never"]
+// Message: There must be no newline after the description of the JSDoc block.
+
+/**
+* A.
+* @typedef {Object} A
+* @prop {boolean} a A.
+*/
+// Options: ["always"]
+// Message: There must be a newline after the description of the JSDoc block.
 ````
 
 The following patterns are not considered problems:
@@ -3370,6 +3427,14 @@ class Bar {
   }
 }
 // Message: The type 'TEMPLATE_TYPE' is undefined.
+
+/**
+ * @type {strnig}
+ */
+var quux = {
+
+};
+// Message: The type 'strnig' is undefined.
 ````
 
 The following patterns are not considered problems:
@@ -5981,6 +6046,8 @@ export class SomeClass {
 
 Checks if the return expression exists in function body and in the comment.
 
+Will also report if multiple `@returns` tags are present.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
@@ -6440,6 +6507,8 @@ function quux () {
 
 Requires returns are documented.
 
+Will also report if multiple `@returns` tags are present.
+
 <a name="eslint-plugin-jsdoc-rules-require-returns-options-11"></a>
 #### Options