There's a policy in Swift-DocC of always printing whatever it's given from the symbol graph; if we could come to a community consensus of what kinds of visibility constraints we would want to handle "by default", then Swift-DocC could do this kind of filtering via something like @ethankusters's suggestion.
Speaking of...
I like the idea of something like @_documentationCategory(...) (making the naming long-form based on @icanzilb's comment) that would special-case forceHidden and forceVisible. Anything else would go into the symbol graph and could be handled by a tool however it would like. Part of me wonders if this would get confused with Swift-DocC's topic groups and SPI over time, though.
The key difference i would see between @_documentationCategory and @_spi is that the latter is already automatically excluded from documentation, whereas the former is only automatically excluded with the proposed forceHidden category; anything else would have to be upon request. I could see this getting a bit thorny with the behavior on @_exported import statements, implementation-wise, but that's something we could work through in the PR.