Add JSDocs for exported GenerateOptions type (#299)

Author: bmish

README.md

@@ -120,17 +120,17 @@ There's also an optional path argument if you need to point the CLI to an ESLint
 
 | Name | Description |
 | :-- | :-- |
-| `--check` | Whether to check for and fail if there is a diff. No output will be written. Typically used during CI. |
+| `--check` | Whether to check for and fail if there is a diff. No output will be written. Typically used during CI. Default: `false`. |
 | `--config-emoji` | Custom emoji to use for a config. Format is `config-name,emoji`. Default emojis are provided for [common configs](./lib/emojis.ts). To remove a default emoji and rely on a [badge](#badge) instead, provide the config name without an emoji. Option can be repeated. |
 | `--ignore-config` | Config to ignore from being displayed. Often used for an `all` config. Option can be repeated. |
-| `--ignore-deprecated-rules` | Whether to ignore deprecated rules from being checked, displayed, or updated (default: `false`). |
-| `--init-rule-docs` | Whether to create rule doc files if they don't yet exist (default: `false`). |
-| `--path-rule-doc` | Path to markdown file for each rule doc. Use `{name}` placeholder for the rule name (default: `docs/rules/{name}.md`). |
+| `--ignore-deprecated-rules` | Whether to ignore deprecated rules from being checked, displayed, or updated. Default: `false`. |
+| `--init-rule-docs` | Whether to create rule doc files if they don't yet exist. Default: `false`. |
+| `--path-rule-doc` | Path to markdown file for each rule doc. Use `{name}` placeholder for the rule name. Default: `docs/rules/{name}.md`. |
 | `--path-rule-list` | Path to markdown file where the rules table list should live. Default: `README.md`. Option can be repeated. |
 | `--rule-doc-notices` | Ordered, comma-separated list of notices to display in rule doc. Non-applicable notices will be hidden. Choices: `configs`, `deprecated`, `fixable` (off by default), `fixableAndHasSuggestions`, `hasSuggestions` (off by default), `options` (off by default), `requiresTypeChecking`, `type` (off by default). Default: `deprecated,configs,fixableAndHasSuggestions,requiresTypeChecking`. |
 | `--rule-doc-section-exclude` | Disallowed section in each rule doc. Exit with failure if present. Option can be repeated. |
 | `--rule-doc-section-include` | Required section in each rule doc. Exit with failure if missing. Option can be repeated. |
-| `--rule-doc-section-options` | Whether to require an "Options" or "Config" rule doc section and mention of any named options for rules with options (default: `true`). |
+| `--rule-doc-section-options` | Whether to require an "Options" or "Config" rule doc section and mention of any named options for rules with options. Default: `true`. |
 | `--rule-doc-title-format` | The format to use for rule doc titles. Defaults to `desc-parens-prefix-name`. See choices in below [table](#--rule-doc-title-format). |
 | `--rule-list-columns` | Ordered, comma-separated list of columns to display in rule list. Empty columns will be hidden. Choices: `configsError`, `configsOff`, `configsWarn`, `deprecated`, `description`, `fixable`, `fixableAndHasSuggestions` (off by default), `hasSuggestions`, `name`, `options` (off by default), `requiresTypeChecking`, `type` (off by default). Default: `name,description,configsError,configsWarn,configsOff,fixable,hasSuggestions,requiresTypeChecking,deprecated`. |
 | `--split-by` | Rule property to split the rules list by. A separate list and header will be created for each value. Example: `meta.type`. |
@@ -156,9 +156,9 @@ There are a few ways to create a config file:
 - An object exported by `.eslint-doc-generatorrc.js`, `.eslint-doc-generatorrc.json`, or any other config file format/name supported by [cosmiconfig](https://github.com/davidtheclark/cosmiconfig#searchplaces)
 - An object under the `eslint-doc-generator` key in `package.json`
 
-Config files support all the [CLI options](#configuration-options) but in camelCase. CLI options take precedence over config file options.
+Config files support all the [CLI options](#configuration-options) but in camelCase.
 
-Using a JavaScript-based config also allows you to provide a `postprocess` function which gets called with the generated content and path to each file as they're processed, to make it easy to apply any custom transformations such as formatting - this is useful if you are using formatting tools such as [`prettier`](#prettier).
+Using a JavaScript-based config file also allows you to provide a `postprocess` function to be called with the generated content and file path for each processed file. Useful for applying custom transformations such as formatting with tools like [`prettier`](#prettier).
 
 Example `.eslint-doc-generatorrc.js`:
 

lib/cli.ts

@@ -100,6 +100,7 @@ export async function run(
 ) {
   const program = new Command();
 
+  // Documentation for options should be kept in sync with README.md and the JSDocs for the `GenerateOptions` type.
   await program
     .version(getCurrentPackageVersion())
     .addArgument(

lib/types.ts

@@ -103,26 +103,71 @@ export enum OPTION_TYPE {
   POSTPROCESS = 'postprocess',
 }
 
-/** The type for the config file and internal generate() function. */
+// JSDocs for options should be kept in sync with README.md and the CLI runner in cli.ts.
+
+/** The type for the config file (e.g. `.eslint-doc-generatorrc.js`) and internal `generate()` function. */
 export type GenerateOptions = {
+  /** Whether to check for and fail if there is a diff. No output will be written. Typically used during CI. Default: `false`. */
   check?: boolean;
+  /**
+   * List of configs and their associated emojis.
+   * Format is `config-name,emoji`.
+   * Default emojis are provided for common configs.
+   * To remove a default emoji and rely on a badge instead, provide the config name without an emoji.
+   */
   configEmoji?: string[];
+  /** Configs to ignore from being displayed. Often used for an `all` config. */
   ignoreConfig?: string[];
+  /** Whether to ignore deprecated rules from being checked, displayed, or updated. Default: `false`. */
   ignoreDeprecatedRules?: boolean;
+  /** Whether to create rule doc files if they don't yet exist. Default: `false`. */
   initRuleDocs?: boolean;
+  /** Path to markdown file for each rule doc. Use `{name}` placeholder for the rule name. Default: `docs/rules/{name}.md`. */
   pathRuleDoc?: string;
+  /** Path to markdown file(s) where the rules table list should live. Default: `README.md`. */
   pathRuleList?: string | string[];
+  /**
+   * Function to be called with the generated content and file path for each processed file.
+   * Useful for applying custom transformations such as formatting with tools like prettier.
+   */
   postprocess?: (
     content: string,
     pathToFile: string
   ) => string | Promise<string>;
+  /**
+   * Ordered, comma-separated list of notices to display in rule doc.
+   * Non-applicable notices will be hidden.
+   * Choices: `configs`, `deprecated`, `fixable` (off by default), `fixableAndHasSuggestions`, `hasSuggestions` (off by default), `options` (off by default), `requiresTypeChecking`, `type` (off by default).
+   * Default: `deprecated,configs,fixableAndHasSuggestions,requiresTypeChecking`.
+   */
   ruleDocNotices?: string;
+  /** Disallowed sections in each rule doc. Exit with failure if present. */
   ruleDocSectionExclude?: string[];
+  /** Required sections in each rule doc. Exit with failure if missing. */
   ruleDocSectionInclude?: string[];
+  /** Whether to require an "Options" or "Config" rule doc section and mention of any named options for rules with options. Default: `true`. */
   ruleDocSectionOptions?: boolean;
+  /** The format to use for rule doc titles. Default: `desc-parens-prefix-name`. */
   ruleDocTitleFormat?: RuleDocTitleFormat;
+  /**
+   * Ordered, comma-separated list of columns to display in rule list.
+   * Empty columns will be hidden.
+   * Choices: `configsError`, `configsOff`, `configsWarn`, `deprecated`, `description`, `fixable`, `fixableAndHasSuggestions` (off by default), `hasSuggestions`, `name`, `options` (off by default), `requiresTypeChecking`, `type` (off by default).
+   * Default: `name,description,configsError,configsWarn,configsOff,fixable,hasSuggestions,requiresTypeChecking,deprecated`.
+   */
   ruleListColumns?: string;
+  /**
+   * Rule property to split the rules list by.
+   * A separate list and header will be created for each value.
+   * Example: `meta.type`.
+   */
   splitBy?: string;
+  /** Link to documentation about the ESLint configurations exported by the plugin. */
   urlConfigs?: string;
+  /**
+   * Link to documentation for each rule.
+   * Useful when it differs from the rule doc path on disk (e.g. custom documentation site in use).
+   * Use `{name}` placeholder for the rule name.
+   */
   urlRuleDoc?: string;
 };