Rule: require that properties in a schema include a description

[JoshuaKGoldberg]

Porting over from typescript-eslint/typescript-eslint#5392: it's theoretically possible for docs generators to use the JSON schema description fields on rule options per https://json-schema.org/draft/2020-12/json-schema-core.html#name-schema-vocabularies. That way auto-generated rule docs can automatically be set up with those descriptions.

Is this something you'd be interested in taking in as a core rule here? I'd imagine it wouldn't be something to enable in the recommended config to start given these descriptions aren't used by the default markdown docs generator. But it might be useful long-term as an opt-in option to enforce that the descriptions live in the page somehow?

---

For a concrete example, in typescript-eslint, the no-explicit-any rule defines descriptions:

schema: [
  {
    type: 'object',
    additionalProperties: false,
    properties: {
      fixToUnknown: {
        description:
          'Whether to enable auto-fixing in which the `any` type is converted to the `unknown` type.',
        type: 'boolean',
      },
      ignoreRestArgs: {
        description: 'Whether to ignore rest parameter arrays.',
        type: 'boolean',
      },
    },
  },
],

...and then https://typescript-eslint.io/rules/no-explicit-any/#options includes them as JSDoc options:

interface Options {
  /**
   * Whether to enable auto-fixing in which the `any` type is converted to the `unknown` type.
   */
  fixToUnknown?: boolean;
  /**
   * Whether to ignore rest parameter arrays.
   */
  ignoreRestArgs?: boolean;
}

const defaultOptions: Options = [
  { fixToUnknown: false, ignoreRestArgs: false },
];

[bmish]

I like this idea. I've always wanted to make schemas more helpful. Maybe a dedicated rule for it called require-meta-schema-description (as it goes beyond require-meta-schema).

Could use these descriptions in bmish/eslint-doc-generator#237 to auto-generate documentation about rule options.

Related to description, including the default property to specify the default value for an option can also be useful for documentation purposes. Maybe another rule require-meta-schema-default for this.

Related:

• New Rule: no-incomplete-schema #296