cargo doc: add option to document specific private items

[Monnoroch]

Problem

I often find myself wanting to expose documentation for a private API that shouldn't be called directly, but is an important enough implementation detail for the advanced users of my library to benefit from reading it.

Proposal

I want to propose a #[doc(visible)] attribute that is analogous to the #[doc(hidden)] one. The new attribute would exclude the labeled item from being removed by the strip-private rustdoc pass.

Alternative solutions considered:

Making the API public.

Solves the problem, but also creates a new one. Especially bad if the API in question is by itself unsafe and relies heavily on implementation of other parts of the library to guarantee safety. I really don't want users to call such an API.

Fake item

I could create a fake public struct / method and add my "hidden" documentation to it. This however does not really solve the problem, as the documentation has links to private items that wouldn't work without making the items public. In addition, it's just a nightmare to debug and support such documentation.

Module-level documentation

Same problem as above, links still will not work.

cargo doc --document-private-items

See rust-lang/cargo#1520.

Also solves the problem, but creates a new one: it adds a ton of clutter making all the documentation much less readable and useful.

[ehuss]

Transferred this issue to rust-lang/rust, as that is where rustdoc issues live.

cc #60884, which sounds similar to me.