Support categories for member APIs

[nex3]

For packages with many different APIs of a given type, it's useful to divide those APIs into categories rather than having them all sorted alphabetically. For example, in test's docs, there are so many matcher functions that it's hard for users to notice non-matcher functions like pumpEventQueue(). It would be very useful to be able to put the matchers in their own sub-section beneath "Functions" to keep everything organized. It would be similarly useful to be able to group classes, fields, and so on.

This is possible today with the {@category} annotation, but that only works for libraries. I'd love to see it generalized.

[devoncarew]

The docs for atom.io do something similar - even for classes w/o a lot of methods, they break up the API into semantic categories:

https://atom.io/docs/api/v1.26.1/NotificationManager

[jcollins-g]

I have generic categorization support in a local branch. It's coming.

[jcollins-g]

Categorization support is shaping up nicely and will be displayed as "api" and "APIs" in dartdoc generated pages. I'm working on the style bits and category page generation now.

[nex3]

How long does it take for a change like this to percolate out into pub.dartlang.org/documentation?

[jcollins-g]

I am planning to publish this week, tomorrow if I can. Afterwards the pub site maintainers have to pick it up, but they typically do that within a few days.

[nex3]

I'm guessing this is live now? Is there any way to tell for sure?

[jcollins-g]

It is published but the pub site maintainers have not yet picked it up:

https://github.com/dart-lang/pub-dartlang-dart/blob/master/pkg/pub_dartdoc/pubspec.yaml#L12

You should be able to try it out locally though with 0.21.1.

[jcollins-g]

dart-lang/pub-dev#1645

[nex3]

Thanks!

[nex3]

It doesn't seem to be working locally for sass/dart-sass@cf2e416 with 0.21.1. The class list looks the same as ever.

[jcollins-g]

It's not clear enough in the docs. I forgot to mention that if the categories are not declared in dartdoc_options.yaml, they're otherwise invisible in the generated docs.

See examples here and here.

[nex3]

I've definitely got DartDoc recognizing the categories now, but it's still not using them to sort either the right-hand column or the main member list.

[jcollins-g]

This is currently working as intended. To get a sorted list of importers, you click on "importers" and then only importers are displayed. Same with "values".

Admittedly this is a bit different than the way categories were handled for libraries, previously. I take it you'd like it do this? It wasn't clear to me that that was a win, but we can do that.

[nex3]

I would like that. I'd actually prefer it to having an alphabetical list of tagged classes.

[jcollins-g]

@nex3 I'll poll the other stakeholders and if I can get some broad agreement there, I'll implement it.

[canthelou-xyz]

categories: they are displayed under a Topics section on the left. To be displayed you need to create a markdown file where the content is the description of the topic.