I fear we may have overcomplicated this. Back to Victoria's original post: We essentially want to productize the _-prefix rule. Note that this rule does more than just impact docs—it affects the generated interface and autocomplete.
In particular I'm concerned we will end up with too many tools and axes on which to slice the API surface of a module. Sometimes it’s appropriate to make compromises in flexibility for simplicity. We’re adding additional technical and cognitive burden when reasoning about conditionally-valid content like links, curation, and relationship-building.
Here's what I suggest:
- We return to Victoria's suggestion, with some bikeshedding:
<access control keyword>(<visible|hidden>), e.g.public(hidden). Or alternatively as per the original proposal rename@_nodocto@_hiddento make it clear it's not just a docs feature, it applies anywhere the symbol would normally be visible. Import access control proposes adding access control modifiers to import statements, so either proposed approach should work for exported imports. - If the symbol is used in source code from within the same target or the symbol graph is built for an access control level below the level specified in the decl (e.g. internal graph for a
public(hidden)symbol), we would emit the symbol into the graph and the symbol would remain available in autocomplete etc. - For backwards compatibility we continue to respect the underscore-prefix rule and allow overriding with something like
public(visible). - Separately, I think there's value in a block directive for conditionally including symbols/articles/paragraphs in docs for particular audiences. For example, this could be used for authoring additional internal-only documentation and to David's point it'd work for any programming language. Perhaps this idea should be explored separately though.
Aside: I’m not too concerned about a documentation compiler needing to understand directives—the author of the comment is already choosing to target doc compilers with a particular feature set when they write a doc comment and we’ve recognized this as an acceptable cost of directives. It's most important that we make a best effort to design syntax that fails gracefully.