Introduce the description field in the rules

[tatomyr]

Is your feature request related to a problem? Please describe.

It's good to keep the docs together with the code. However, currently, built-in rules are authored separately from the corresponding documentation.

Another common problem is that a rule can be unclear (requires a more detailed explanation).

Describe the solution you'd like

It might be helpful to introduce a description field (similar to what we have in OAS) that would explain the intention of the rule or provide some examples of using it. The descriptions themselves should utilize the markdown/markdoc format.

Also, we need to implement a way of creating docs from the descriptions.

This will help to keep the docs and the code in sync as we can generate the actual documentation out of the descriptions.

We can also show an extended hint of a rule in an editor extension.

Consider this example of a Redocly config:

rules:
  rule/something:
    ...
    description: |
       Some description to explain what the rule does (like examples).

For build-in rules, it should be predefined but with a possibility to override the existing one, e.g.:

rules:
  info-license: 
    severity: error
    description: A custom description that explains why we need this field and maybe a link to a list of the possible licences.

I'm not clear, however, if it'd be better to reference the existing .md files from the code or actually move the descriptions into the code.

@adamaltman please add anything I missed here.

Describe alternatives you've considered

We may continue writing the rules and the docs separately.

[lornajane]

This is a nice idea! I think it would be great to have descriptions of rules, and to be able to get a ruleset in summary-for-humans format. I especially like the idea of using markdown in the description so that we can link to further resources where it makes sense to do that.

I don't anticipate us replacing our existing (very good) docs for the built-in rules, but most rules won't publish separate pages with such clear explanation of configuration and examples and so on - and I'm not sure it makes sense to have all that information as a description.

[jeremyfiel]

this is tangentially related to #1052

[lornajane]

Looping back on how this should look. I think we should use an OpenAPI -style description for our rules. So 1-2 sentences of markdown is the expected format, but not a book/article level of information. The goal is to describe what a rule does and why - for our built-in rules we could expand on the one-liners in the built-in rules docs. For configurable rules, we could give meaningful descriptions in all our examples to show how the rules should be used. (I'm happy to help add the content to go alongside the functionality here)

How these should be presented:

• a lint-summary command that takes an API or alias as input (only one!) and outputs the rules that will be applied and their descriptions, in human readable format (with JSON as a format option, and maybe markdown?)
• in VSCode, I'm not sure what would work best. We show the error rather than the rule where a problem occurs. How about offering a link to the rule that caused the message, in a rendered page of the rules being used to lint. We might want to break this part out to a followup issue in the VSCode project.

[jeremyfiel]

In VSC, can you populate the hover popup on an error node with the description?

Currently, it uses the message value but adding the description would provide more context on the rule.