docs: add TOC to rule files; add fixer placeholder sections

Author: brettz9

.README/rules/check-access.md

@@ -1,4 +1,6 @@
-### `check-access`
+# `check-access`
+
+{"gitdown": "contents", "rootId": "check-access"}
 
 Checks that `@access` tags use one of the following values:
 
@@ -11,6 +13,8 @@ Also reports:
 - Use of multiple instances of `@access` (or the `@public`, etc. style tags)
   on the same doc block.
 
+## Context and settings
+
 |||
 |---|---|
 |Context|everywhere|
@@ -19,4 +23,10 @@ Also reports:
 |Settings||
 |Options||
 
-<!-- assertions checkAccess -->
+## Failing examples
+
+<!-- assertions-failing checkAccess -->
+
+## Passing examples
+
+<!-- assertions-passing checkAccess -->

.README/rules/check-alignment.md

@@ -1,11 +1,25 @@
-### `check-alignment`
+# `check-alignment`
+
+{"gitdown": "contents", "rootId": "check-alignment"}
 
 Reports invalid alignment of JSDoc block asterisks.
 
+## Fixer
+
+Fixes alignment.
+
+## Context and settings
+
 |||
 |---|---|
 |Context|everywhere|
 |Tags|N/A|
 |Recommended|true|
 
-<!-- assertions checkAlignment -->
+## Failing examples
+
+<!-- assertions-failing checkAlignment -->
+
+## Passing examples
+
+<!-- assertions-passing checkAlignment -->

.README/rules/check-examples.md

@@ -1,4 +1,6 @@
-### `check-examples`
+# `check-examples`
+
+{"gitdown": "contents", "rootId": "check-examples"}
 
 > **NOTE**: This rule currently does not work in ESLint 8 (we are waiting for
 > [issue 14745](https://github.com/eslint/eslint/issues/14745)).
@@ -7,11 +9,11 @@ Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules. Also
 has options to lint the default values of optional `@param`/`@arg`/`@argument`
 and `@property`/`@prop` tags or the values of `@default`/`@defaultvalue` tags.
 
-#### Options
+## Options
 
 The options below all default to no-op/`false` except as noted.
 
-##### `captionRequired`
+### `captionRequired`
 
 JSDoc specs use of an optional `<caption>` element at the beginning of
 `@example`.
@@ -21,7 +23,7 @@ the beginning of any `@example`.
 
 Used only for `@example`.
 
-##### `exampleCodeRegex` and `rejectExampleCodeRegex`
+### `exampleCodeRegex` and `rejectExampleCodeRegex`
 
 JSDoc does not specify a formal means for delimiting code blocks within
 `@example` (it uses generic syntax highlighting techniques for its own
@@ -49,7 +51,7 @@ 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.
 
-##### `paddedIndent`
+### `paddedIndent`
 
 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
@@ -69,7 +71,7 @@ out before evaluation.
 
 Only applied to `@example` linting.
 
-##### `reportUnusedDisableDirectives`
+### `reportUnusedDisableDirectives`
 
 If not set to `false`, `reportUnusedDisableDirectives` will report disabled
 directives which are not used (and thus not needed). Defaults to `true`.
@@ -80,7 +82,7 @@ Inline ESLint config within `@example` JavaScript is allowed (or within
 needed by the resolved rules will be reported as with the ESLint
 `--report-unused-disable-directives` command.
 
-#### Options for Determining ESLint Rule Applicability (`allowInlineConfig`, `noDefaultExampleRules`, `matchingFileName`, `configFile`, `checkEslintrc`, and `baseConfig`)
+## Options for Determining ESLint Rule Applicability (`allowInlineConfig`, `noDefaultExampleRules`, `matchingFileName`, `configFile`, `checkEslintrc`, and `baseConfig`)
 
 The following options determine which individual ESLint rules will be
 applied to the JavaScript found within the `@example` tags (as determined
@@ -131,7 +133,7 @@ by decreasing precedence:
 * `baseConfig` - Set to an object of rules with the same schema
   as `.eslintrc.*` for defaults.
 
-##### Rules Disabled by Default Unless `noDefaultExampleRules` is Set to `true`
+### Rules Disabled by Default Unless `noDefaultExampleRules` is Set to `true`
 
 * `eol-last` - Insisting that a newline "always" be at the end is less likely
   to be desired in sample code as with the code file convention.
@@ -166,17 +168,25 @@ expression-oriented rules will be used by default as well:
 * `no-unused-expressions` - Disabled.
 * `chai-friendly/no-unused-expressions` - Disabled.
 
-##### Options for checking other than `@example` (`checkDefaults`, `checkParams`, or `checkProperties`)
+### Options for checking other than `@example` (`checkDefaults`, `checkParams`, or `checkProperties`)
 
 * `checkDefaults` - Whether to check the values of `@default`/`@defaultvalue` tags
 * `checkParams` - Whether to check `@param`/`@arg`/`@argument` default values
 * `checkProperties` - Whether to check `@property`/`@prop` default values
 
+## Context and settings
+
 |||
 |---|---|
 |Context|everywhere|
 |Tags|`example`|
 |Recommended|false|
 |Options| *See above* |
 
-<!-- assertions checkExamples -->
+## Failing examples
+
+<!-- assertions-failing checkExamples -->
+
+## Passing examples
+
+<!-- assertions-passing checkExamples -->

.README/rules/check-indentation.md

@@ -1,4 +1,6 @@
-### `check-indentation`
+# `check-indentation`
+
+{"gitdown": "contents", "rootId": "check-indentation"}
 
 Reports invalid padding inside JSDoc blocks.
 
@@ -16,11 +18,11 @@ the following description is not reported:
  */
 ```
 
-#### Options
+## Options
 
 This rule has an object option.
 
-##### `excludeTags`
+### `excludeTags`
 
 Array of tags (e.g., `['example', 'description']`) whose content will be
 "hidden" from the `check-indentation` rule. Defaults to `['example']`.
@@ -42,11 +44,19 @@ report a padding issue:
  */
 ```
 
+## Context and settings
+
 |||
 |---|---|
 |Context|everywhere|
 |Tags|N/A|
 |Recommended|false|
 |Options| `excludeTags` |
 
-<!-- assertions checkIndentation -->
+## Failing examples
+
+<!-- assertions-failing checkIndentation -->
+
+## Passing examples
+
+<!-- assertions-passing checkIndentation -->

.README/rules/check-line-alignment.md

@@ -1,10 +1,16 @@
-### `check-line-alignment`
+# `check-line-alignment`
+
+{"gitdown": "contents", "rootId": "check-line-alignment"}
 
 Reports invalid alignment of JSDoc block lines. This is a
 [standard recommended to WordPress code](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/#aligning-comments),
 for example.
 
-#### Options
+## Fixer
+
+(TODO)
+
+## Options
 
 This rule allows one optional string argument. If it is `"always"` then a
 problem is raised when the lines are not aligned. If it is `"never"` then
@@ -16,12 +22,12 @@ ensure that at least one space is present after the asterisk delimiter.
 
 After the string, an options object is allowed with the following properties.
 
-##### `tags`
+### `tags`
 
 Use this to change the tags which are sought for alignment changes. Defaults to an array of
 `['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return']`.
 
-##### `customSpacings`
+### `customSpacings`
 
 An object with any of the following keys set to an integer. Affects spacing:
 
@@ -33,16 +39,18 @@ An object with any of the following keys set to an integer. Affects spacing:
 
 If a spacing is not defined, it defaults to one.
 
-##### `preserveMainDescriptionPostDelimiter`
+### `preserveMainDescriptionPostDelimiter`
 
 A boolean to determine whether to preserve the post-delimiter spacing of the
 main description. If `false` or unset, will be set to a single space.
 
-##### `wrapIndent`
+### `wrapIndent`
 
 The indent that will be applied for tag text after the first line.
 Default to the empty string (no indent).
 
+## Context and settings
+
 |||
 |---|---|
 |Context|everywhere|
@@ -51,4 +59,10 @@ Default to the empty string (no indent).
 |Aliases|`arg`, `argument`, `prop`, `return`|
 |Recommended|false|
 
-<!-- assertions checkLineAlignment -->
+## Failing examples
+
+<!-- assertions-failing checkLineAlignment -->
+
+## Passing examples
+
+<!-- assertions-passing checkLineAlignment -->

.README/rules/check-param-names.md

@@ -1,9 +1,15 @@
-### `check-param-names`
+# `check-param-names`
+
+{"gitdown": "contents", "rootId": "check-param-names"}
 
 Ensures that parameter names in JSDoc are matched by corresponding items in
 the function declaration.
 
-#### Destructuring
+## Fixer
+
+(Todo)
+
+## Destructuring
 
 Note that by default the rule will not report parameters present on the docs
 but non-existing on the function signature when an object rest property is part
@@ -28,17 +34,17 @@ other properties, so in looking at the docs alone without looking at the
 function signature, the disadvantage of enabling this option is that it
 may appear that there is an actual property named `extra`.
 
-#### Options
+## Options
 
-##### `checkRestProperty`
+### `checkRestProperty`
 
 See the "Destructuring" section. Defaults to `false`.
 
-##### `checkTypesPattern`
+### `checkTypesPattern`
 
 See `require-param` under the option of the same name.
 
-##### `enableFixer`
+### `enableFixer`
 
 Set to `true` to auto-remove `@param` duplicates (based on identical
 names).
@@ -47,25 +53,25 @@ Note that this option will remove duplicates of the same name even if
 the definitions do not match in other ways (e.g., the second param will
 be removed even if it has a different type or description).
 
-##### `allowExtraTrailingParamDocs`
+### `allowExtraTrailingParamDocs`
 
 If set to `true`, this option will allow extra `@param` definitions (e.g.,
 representing future expected or virtual params) to be present without needing
 their presence within the function signature. Other inconsistencies between
 `@param`'s and present function parameters will still be reported.
 
-##### `checkDestructured`
+### `checkDestructured`
 
 Whether to check destructured properties. Defaults to `true`.
 
-##### `useDefaultObjectProperties`
+### `useDefaultObjectProperties`
 
 Set to `true` if you wish to avoid reporting of child property documentation
 where instead of destructuring, a whole plain object is supplied as default
 value but you wish its keys to be considered as signalling that the properties
 are present and can therefore be documented. Defaults to `false`.
 
-##### `disableExtraPropertyReporting`
+### `disableExtraPropertyReporting`
 
 Whether to check for extra destructured properties. Defaults to `false`. Change
 to `true` if you want to be able to document properties which are not actually
@@ -75,11 +81,20 @@ item at the same level is destructured as destructuring will prevent other
 access and this option is only intended to permit documenting extra properties
 that are available and actually used in the function.
 
+## Context and settings
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Options|`allowExtraTrailingParamDocs`, `checkDestructured`, `checkRestProperty`, `checkTypesPattern`, `useDefaultObjectProperties`, `disableExtraPropertyReporting`|
 |Tags|`param`|
 |Aliases|`arg`, `argument`|
 |Recommended|true|
-<!-- assertions checkParamNames -->
+
+## Failing examples
+
+<!-- assertions-failing checkParamNames -->
+
+## Passing examples
+
+<!-- assertions-passing checkParamNames -->

.README/rules/check-property-names.md

@@ -1,11 +1,17 @@
-### `check-property-names`
+# `check-property-names`
+
+{"gitdown": "contents", "rootId": "check-property-names"}
 
 Ensures that property names in JSDoc are not duplicated on the same block
 and that nested properties have defined roots.
 
-#### Options
+## Fixer
+
+(Todo)
 
-##### `enableFixer`
+## Options
+
+### `enableFixer`
 
 Set to `true` to auto-remove `@property` duplicates (based on
 identical names).
@@ -14,6 +20,8 @@ Note that this option will remove duplicates of the same name even if
 the definitions do not match in other ways (e.g., the second property will
 be removed even if it has a different type or description).
 
+## Context and settings
+
 |||
 |---|---|
 |Context|Everywhere|
@@ -22,4 +30,10 @@ be removed even if it has a different type or description).
 |Aliases|`prop`|
 |Recommended|true|
 
-<!-- assertions checkPropertyNames -->
+## Failing examples
+
+<!-- assertions-failing checkPropertyNames -->
+
+## Passing examples
+
+<!-- assertions-passing checkPropertyNames -->