Specified categories were disapperared from the API doc

[AlexV525]

The request cfug/dio#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: cfug/dio#2344 (comment)

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 #4012, which is probably the same use case.

[jonasfj]

I did a bit of investigation, we have a test case covering the current behavior:

dartdoc/test/options_test.dart

Lines 407 to 439 in 95f4208

	void test_categoriesAreOnlyTrackedWhenUsed() async {
	await createPackage(
	dartdocOptions: '''
	dartdoc:
	categories:
	One:
	markdown: one.md
	Two:
	markdown: two.md
	''',
	libFiles: [
	d.file('lib.dart', '''
	library 'lib1';
	/// {@category One}
	class C1 {}
	'''),
	],
	files: [
	d.file('one.md', ''),
	d.file('two.md', ''),
	],
	);
	final packageGraph = await bootBasicPackage(
	packagePath,
	packageMetaProvider,
	packageConfigProvider,
	);
	final package = packageGraph.packages
	.firstWhere((element) => element.name == packageName);
	expect(
	package.documentedCategoriesSorted.map((c) => c.name), equals(['One']));
	}

Introduced in:
#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:

• Have an option to generate docs without categories #4012
• Provide a way to compile and link to non-README documentation files #1096

Maybe we should introduce a "pages" concept.