Custom categories from code comments

[FabienLydoire]

Hello !
I'm wondering if it is possible to create categories and mark classes, strucs, enum... in those categories from comments in the code.

I do not want to maintain a list of custom categories in the jazzy configuration file : the maintenance price is too high.

I would image something like

/// MyClass documentation
/// Category: MyCategory
class MyClass {
}

[johnfairh]

Yes I think this is doable -- I would go with syntax like - docs-category: MyCategory to fit in with the callout convention, this will also hide it in Quick Help. Can offer some tips on where to start if someone wants to implement it.

[Nolanlemahn]

Hey - I know this is old, but I wanted to bump this as something like this would be useful for our use case.

I don't know if we have the bandwidth to assist with implementation, but I'd still be interested in what the pointers would look like.

[johnfairh]

Broadly, without thinking too hard about it:

• The requirement here seems to be to discover a category/article tree akin to that provided by the config file custom_categories while the source declarations are parsed, then to use that tree instead of (in addition to?) the config file's tree
• May as well spin up a new file to hold the discovered category tree and work on it, pull any code dedicated to custom categories into here
• Detect category paths when processing a declaration --- either using a custom doc comment as described above, or, in space year 2023, the @_documentation(metadata:) attribute which is intended for purposes like this. Either way, pull it out in make_doc_info
• Either store the the category tree in exactly the same format as the config file would produce, or provide a getter to massage the tree into that format, and use it instead of the config file version in group_custom_categories.

[Nolanlemahn]

Thanks @johnfairh - having that on paper will be useful in case we find bandwidth to contribute.

An additional follow-up: any early design decisions on how this "might" function with #624 / #982? (IE - I think if possible, nested categorization should go in first, but I imagine you have an idea on how that might affect the implementation here.)

[johnfairh]

They're independent - just need the design for category paths here to allow for multiple levels, eg. @_documentation(metadata: "jazzy-category:Main/Sub/Subsub").

IIRC the thing blocking the nested category stuff is design/theme work for the left nav.