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.