Consider deprecating the `showUndocumentedCategories` option

[jonasfj]

Why shouldn't we always have showUndocumentedCategories: true? (this isn't the default today).

If someone wrote an {@category foo} tag, then why wouldn't we want to always include it? If authors don't want a category to show up in documentation, then don't make a category, do they have other purposes? We'd need to investigate if any of our major users would be affected by changing the default for this option.

Reading the code, I suspect that today, a category is only displayed if, either:

• (A) showUndocumentedCategories: true is specified in dartdoc_options.yaml, OR
• (B) Both of the following statements hold:
  • (B.1) The category is declared in dartdoc_options.yaml, and,
  • (B.2) There is a markdown file for the category declared in dartdoc_options.yaml.

This is mostly motivated by wanting to reduce the number of options. I think we could consider:

Option (i): Always show all categories

We always display all categories, whether they are declared in dartdoc_options.yaml or not.

We'd need to investigate if any major users would be negatively affected.

I suspect we could make this change and simply declare showUndocumentedCategories deprecating, printing a warning for anyone using the option.

Pros:

• We simply options

Cons:

• Typos in {@category fooo} annotations won't trigger warnings.
• Users relying on current behavior might have to remove {@category foo} annotations from their code.

Option (ii): Require that categories are declared dartdoc_options.yaml

We require that all categories are declared in dartdoc_options.yaml, but we don't require that they have a markdown file (as is currently required in condition (B.2)).

For this I suspect we'd need to:

• Deprecate showUndocumentedCategories
• When encountering an {@category foo} annotation where foo isn't declared in dartdoc_options.yaml:
  • Ignore the {@category foo} annotation
  • Print a warning stating that category foo isn't declared in dartdoc_options.yaml!

Pros:

• We simply options
• Typos in {@category fooo} annotations will trigger a warning (at-least in dartdoc).

Cons:

• Users will need to create a dartdoc_options.yaml to use categories (this is also the case today).
• Users relying on showUndocumentedCategories: true will need to change their behavior.