Cascade namespace tags to individual API members in rendered doc

[erikadoyle]

Search Terms

tag namespace cascade

Problem

In using Typedoc to generate reference documentation for the Microsoft Teams JavaScript client library, we occasionally create documentation bugs when a developer tags a namespace (as @deprecated, or @beta, for example) and then forgets to manually tag each individual member API with that same tag. As some of our generated documentation pages are rather long, our customers might not notice (or realize) that the entire namespace (implying all member API too) are marked for a certain state.

Suggested Solution

The team building the @microsoft/teams-js library would like to propose a Typedoc enhancement whereby tagging a namespace then applies the same tag to constituent member API sections of the doc as well, perhaps overridden by any tags specified directly on individual API members in source. Thanks for your consideration!

[Gerrit0]

It seems reasonable to me to cascade modifier tags (likely to all children, not just namespace children)... There probably needs to be a way to configure mutually exclusive tags, since otherwise there wouldn't be a way to tell if a @beta tag on a namespace copied to a class with @alpha should take precedence.

This might need to wait until 0.24 for a breaking change - TypeDoc's treatment of @public would be really bad to cascade... I've been wanting to change this for a while.

[Gerrit0]

I ended up deciding as a first pass to make the mutually exclusive configuration present only in TypeDoc's source code, can always make it an option if someone needs it in the future, but start simple..

In 0.26, this will be controlled by the --cascadedModifierTags option, which defaults to copying "@alpha", "@beta", "@experimental"

[Gerrit0]

Fixed with TypeDoc 0.26, which is releasing 2024/06/21

[erikadoyle]

Thanks so much @Gerrit0!