docgen: hoist constants using the @constant JSDoc tag

[oandregal]

When generating docs for an API, constants could be grouped at the top of the API section. Suggested at #14265 (comment)

One way to implement this would be to group the symbols that are constants, as declared by the @constant JSDoc tag.

Note the related @const tag.

[aduth]

Pulling discussion from #14266 (comment) here :

We have two easy options: document the symbols as they appear in the export statements VS alphabetical order. None are perfect. A third option I can think of would be to plug a specific --sort method option to docgen as to address different package sorting mechanism.

I like the first idea here. Is there any challenge to this, or downside?

[oandregal]

@aduth We should create an issue for sorting! :)

I like the first idea here. Is there any challenge to this, or downside?

One good thing about using the export order to sort the API would be that we could group things together: like having registerPlugin just before unregisterPlugin. Or what you mentioned about having the most used functions first.

The downside is that it requires manual curation. I don't think we have now the amount of time required to curate all the packages. And, even if we did, I don't think we could sustain it over time: being almost at 400 contributors means a high-potential for wildly different curations of things, but also changes made by contributors unaware of the proper order.

Alphabetical takes that burden out of the table. But also a strong argument for it is that API docs are reference documentation (like a dictionary, which is optimized for lookup). This is in contrast with onboarding documentation (tutorials and such), where you present the most relevant things first.

Said that: I look forward to bringing more grouping abilities. This issue is just one possibility. The data module would be a good use case to explore: how can we group selectors, action creators, HOCs, etc. in the API docs without involving manual curation? I wish jsdoc had any way to define artifacts in one semantic level up, at the domain layer (I mean: from @class/@function/@constant to @selector/@action/etc).

[oandregal]

I wish jsdoc had any way to define artifacts in one semantic level up, at the domain layer (I mean: from @class/@function/@constant to @selector/@action/etc.).

Although @typedef could be something to explore, it's limited in that only serves to document the type of a parameter or the output. It's not about the signature of the artifact (which is what defines a selector, action creator, etc).

[aduth]

@aduth We should create an issue for sorting! :)

Sorry, did not mean to side-track, just seemed that sorting could supersede the need for specifically hoisting constants.

But also a strong argument for it is that API docs are reference documentation (like a dictionary, which is optimized for lookup). This is in contrast with onboarding documentation (tutorials and such), where you present the most relevant things first.

I like this argument, and your follow-up point about groupings. I can't say I have any advice to offer. The idea sounds similar to something like PHPUnit's @group annotation. Is there any specific problem we might face if we were to use a tag not strictly part of the JSDoc family?

[oandregal]

One thing I had hopes in was the @kind tag. Tried to use it like @kind selector, but that makes the linter unhappy.

Bizarrely enough, what doesn't make the linter unhappy is to use our own tag @gutenberg selector 🤷‍♂️ doctrine also passes it through, so it's picked up by docgen and ends up in the JSON that it generates. We'd only need to teach the formatters to use this in some way.

A different approach would be to use the @implements tag such as @implements {selector} an extra description. I like this approach better. It fits with our purpose (describing domain's semantics) and it's spec/future-proof (at least any tool that claims JSDoc support should play nicely with this). Created #14333

[oandregal]

I'm triagging issues we don't plan to tackle. We can reopen if it regains interest.