rustdoc: Mark public items, instead of private items, with --document-private-items

[camelid]

Looking at the rustc API docs (doc.rust-lang.org/nightly/nightly-rustc), the result of #95024 still feels really noisy to me.

I have two ideas for ways to improve it:

1. Move the lock to the left "gutter", i.e. the left side of the name, but in a column to the left of all the names. This would make it look a bit less chaotic. Not sure how technically feasible this is, and it'd still have noise from the locks themselves.

2. Instead of marking private items, mark public items. This would only happen when --document-private-items is passed. Usually crates have a lot more private items than public ones – which is even more likely for the kinds of crates that people use --document-private-items on – in which case the markings would cause less noise.

   Also, my understanding is the original purpose of this PR was to make it easier to see which parts of the API are public. When all but a few items are marked, it's hard to find the unmarked items, whereas when just a few are marked, it's easier to find those marked items. So I think doing this would accomplish the goal even better.

   The only issue I can think of is figuring out what icon to use. IntelliJ seems to use an open lock: https://stackoverflow.com/questions/57427175/intellij-not-showing-private-or-public-icon-aka-visibility-icon-for-methods-aka

I think I'd prefer option 2. What do you think about it?

Originally posted by @camelid in #95024 (comment)

[jsha]

Another possibility would be to move the lock to the right-hand side, at the beginning of the documentation (if there is any).

I think we should really avoid putting things in the gutter wherever possible - the [-] and § are rare exceptions and have in common that they are UI elements, not documentation. That inclines me away from Option 1.

For option 2: I hesitate to draw the conclusion that all crates are as heavy on private items as rustc, but you make a good point that private items at least outnumber public ones in most crates. I think it's worth a try. As for icon: maybe an eye for "visible"?

[GuillaumeGomez]

I'm not a big fan of option 2 because it creates an incoherence between "normal" documentation rendering and private documentation rendering. Marking items that are always present in only a given case seems weird. I don't have an idea on how to reduce the noise though. I think the problem will remain the same in other crates if we add an icon on public items instead of private ones.

[koehlma]

For what it's worth, after living with the 🔒 for a while now, I can say that it is very useful for my workflow and projects. :)

I do not think that the lock is generally noise in certain crates (with a high number of private items) and generally signal in others (with a low number of private items). As I see it, the challenge with noise vs. signal is that it is highly context-dependent whether something is noise or signal. At least for the stuff I work on, the lock is signal most of the time. Also, have a look at rustc_hir for example – there it feels also quite reasonable and helpful.

Ideally, the documentation would provide exactly the right amount of information needed by a particular developer in a given context. Maybe the solution is to add an option to the Rustdoc settings such that the lock can be turned off and on based on reader preferences?

[camelid]

We're generally trying to avoid adding more configuration since it increases UI complexity and makes debugging harder. So I think it'd be better to always show the lock than make it configurable.