@_nodoc attribute for hiding symbols from the symbol graph

[taylorswift]

@QuietMisdreavus

Alternately, something i thought of while writing the previous part up: If we keep the "underscore logic", the names could be something like shouldBeVisible and treatAsInternal, which provide more insight into what's happening than relying on an understanding of what happens when you prefix a symbol name with an underscore. The "should be" modifier provides a softer implication than "force" would, but might have the same kind of confusion. What do you think?

i think the main goal here is the attribute should be clear on what it does, which is how we prevent it from becoming a footgun.

the envisioned use case of @documentation is to override the default inferred behavior, so @documentation(treatAsInternal) wouldn’t really help me understand what @documentation(treatAsInternal) does, since @documentation(_:) can also be used to make internal symbols visible.

@QuietMisdreavus

It would require more responsibility from package authors to create coherent documentation.

as a package author, i care about whether a symbol is visible or not. so the compiler should just ask me yes or no “should this symbol be displayed or not”. this doesn’t have to be black and white; we could also have a “contributors only” mode, where we would now have 3 ‘flavors’ of visibility:

1. always visible (@documentation(visibility: all))
2. visible to contributors (@documentation(visibility: contributors))
3. never visible (@documentation(visibility: never))

i don’t actually think this is a radical departure from what you have proposed, i have just changed the namings slightly to avoid overloading on concepts like public, internal, “underscored”, etc., that we are simultaneously overriding.