Request to group concepts together, across libraries

[sethladd]

Related to flutter/flutter#8906

We'd like to:

• somehow say "these concepts are all part of the same concept/category/grouping"
• somehow say "this is the homepage for that concept"

[jcollins-g]

Would like to know more here. This sounds like you want something (A comment? A separate file?) that declares a "concept" with a description or similar. The closest thing dartdoc does similar to this is the top level index for a package, so my first inclination would be to generate something that looks like that. If we see this concept referenced via a decorator or similar for a particular identifier, cross-link that identifier with the concept's top level page.

You could sort of do that now with an arbitrary decorator you declare for the concept, say @MyConcept. And in @MyConcept's doc you could describe the concept. But that would only link one direction right now, I think.

[Hixie]

@sethladd, @InMatrix - can you give @jcollins-g a sketch of what you are hoping we can do here?

[InMatrix]

We would love to be able to annotate an API's category and subcategory in its source code and generate a file similar to the hand-crafted widgets.json, which backs the widget catalog. Some of the categories are across library boundaries such as "layout models."

[InMatrix]

@sethladd did you envision other use of the categorization mechanism discussed here? On second thought, keeping widgets.json updated is not too bad. So I'm not sure if it's worth pursuing a more sophisticated solution.

[jcollins-g]

Ah. So, you're not actually looking for a front-page for the concept, but rather for dartdoc to generate jsons using the custom annotation you described?

[sethladd]

@Hixie if you can add a category and subcategory annotation to widgets, we can extract out a beautiful widget catalog and look at dartdoc organization options, as @InMatrix suggests.

I opened flutter/flutter#10344 to ask for a solution in the source code. From there, we can look at display options.

[InMatrix]

This feature will be especially useful to show animation-related widgets in a single place. They are currently scattered in the Animation library, the Material library, and the Widget library.

[jcollins-g]

Work for #1610 is putting this feature within reach. A tag inside the documentation for a symbol will be able to add it to a category. The structure built for #1610 just needs to be extended to more symbol types.

[jcollins-g]

This is actually complete as of a couple versions ago.