Specified categories were disapperared from the API doc

[AlexV525]

The request https://github.com/cfug/dio/pull/2344 is trying to remove the categories doc annotation, but then the topics disappeared.

However, the doc of the package pxl.dart seems working well while we have a similar configuration.

[srawlins]

Please elaborate on what problem you are seeing. What did you try to do? What was the expected result? What was the actual result?

[AlexV525]

https://pub.dev/documentation/dio/latest/dio/

There are two topics in the doc. The pull request is about removing the category annotation: https://github.com/cfug/dio/blob/b16a611a14b8b8a4cb7f2556628a5f030c315ffd/dio/lib/dio.dart#L4-L5

After removed, those topics are disappeared from the doc: https://github.com/cfug/dio/pull/2344#issuecomment-2561788533

We have configured categories in the yaml: https://github.com/cfug/dio/blob/main/dio/dartdoc_options.yaml

I looked at the package pxl.dart and it doesn't seem to have extra configuration but topics are displayed correctly in its doc.

[AlexV525]

Hi @srawlins , sorry for the previous lack of detailed comment. Is this something we can move on now?

[srawlins]

Yes, that should be enough to start an investigation.

[jonasfj]

I suspect showUndocumentedCategories: true just causes categories for which no markdown file exists to be included in the list of categories.

I don't think there is an option to include categories that are not referenced with {@Category ...} -- I suppose that maybe that's what showUndocumentedCategories should do -- or maybe we should have an showUnusedCategories option.

[jonasfj]

See also https://github.com/dart-lang/dartdoc/issues/4012, which is probably the same use case.

[jonasfj]

I did a bit of investigation, we have a test case covering the current behavior: https://github.com/dart-lang/dartdoc/blob/95f4208e094a2832dd29a9591d9b95ddf6632174/test/options_test.dart#L407-L439

Introduced in: https://github.com/dart-lang/dartdoc/pull/2965

I can see the argument that categories shouldn't be used for text documentation. But also that in the UI categories are currently called "topics", so it's certainly attractive to use them that way.

There currently two bugs asking for text documentation pages:

• https://github.com/dart-lang/dartdoc/issues/4012
• https://github.com/dart-lang/dartdoc/issues/1096

Maybe we should introduce a "pages" concept.