Runtime toggle for private/hidden items documentation

[ojeda]

In some projects, it can be useful to see private/hidden items/documentation/details (and /* private fields */ etc.) without having to go into the source view, which isn't as nice.

Instead of re-rendering the documentation with --document-private-items and --document-hidden-items, it would be very interesting to have a runtime toggle (i.e. in the web UI) that users could click to show hidden and/or private items on the fly.

This feature would also mean that we would already get checking for private/hidden items, i.e. it could be an alternative for #149105 for those that want to use the runtime toggle anyway.

This can be worked around on the user side by generating every documentation set needed and then adding custom UI. Of course, that is slower, takes more space, doesn't allow for an implementation that avoids reloading, users need to reimplement the same idea, etc.

#141299

Cc @GuillaumeGomez @fmease @lolbinarycat

@rustbot label T-rustdoc
@rustbot label A-intra-doc-links
@rustbot label A-rust-for-linux

[GuillaumeGomez]

I think an acceptable approach for this would be to add this toggle (or these if we want a separate toggle for hidden items) only when the --document-private-items is used. Meaning that the RfL docs would be built with this flag all the time.

Then question becomes: do we want this toggle to be enabled or disabled by default. And also, do we want users to be able to change that when they generate docs?

[ojeda]

Yeah, definitely, it could perhaps be implied by --document-*-items.

For Rust for Linux, I think having the private/hidden with toggle all the time would be fine, unless I am missing something. I checked how long it takes to build with both --document-*-items flags enabled, and so far it looks essentially the same time.

Well, in fact, it seems consistently slightly faster to do it with the flags enabled, because it actually generates less content in disk. For instance, I see a lot of redirecting pages disappear from core arch intrinsics.

Looking around, I see that indeed the behavior around re-exports changes substantially, e.g. when the flags are enabled, rustdoc will show the private module our clk module contains, plus a Re-export section, but it will on top of that remove the re-exports from the "normal" list (the one it would generate without the flags), so users need to click on the private module. With the toggle, this is probably fine (although I guess it could be confusing, since things move around rather than just being "additions"). Without the toggle (i.e. a project using the flags as-is today), it means users don't get to ever see the "normal" documentation. In that sense, the toggle feature helps a bit.

[GuillaumeGomez]

Well, much less work to be done on reexports since we don't need to keep track of what was removed. Let me bring this up to next rustdoc meeting then.