rustdoc: add private items toggle

[lolbinarycat]

r? @ghost

@ojeda here's a MVP implementation of the feature you were talking about.

currently the search isn't affected at all, and additionally, there's no way to toggle the feature at the command line.

(DO NOT MERGE: the feature would be insta-stable)

[rust-log-analyzer]

The job mingw-check-tidy failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

info: removing rustup binaries
info: rustup is uninstalled
##[group]Image checksum input
mingw-check-tidy
# We use the ghcr base image because ghcr doesn't have a rate limit
# and the mingw-check-tidy job doesn't cache docker images in CI.
FROM ghcr.io/rust-lang/ubuntu:22.04

ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  g++ \
---

COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
COPY host-x86_64/mingw-check/validate-error-codes.sh /scripts/

# NOTE: intentionally uses python2 for x.py so we can test it still works.
# validate-toolstate only runs in our CI, so it's ok for it to only support python3.
ENV SCRIPT TIDY_PRINT_DIFF=1 python2.7 ../x.py test \
           --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --allow-unsafe --generate-hashes reuse-requirements.in
---
#12 2.846 Building wheels for collected packages: reuse
#12 2.847   Building wheel for reuse (pyproject.toml): started
#12 3.058   Building wheel for reuse (pyproject.toml): finished with status 'done'
#12 3.059   Created wheel for reuse: filename=reuse-4.0.3-cp310-cp310-manylinux_2_35_x86_64.whl size=132719 sha256=d2a2565e7037ad3883fb9337653f2e25bbb588534fbef3697286cbc26d1bf634
#12 3.059   Stored in directory: /tmp/pip-ephem-wheel-cache-3thlf5q4/wheels/3d/8d/0a/e0fc6aba4494b28a967ab5eaf951c121d9c677958714e34532
#12 3.061 Successfully built reuse
#12 3.062 Installing collected packages: boolean-py, binaryornot, tomlkit, reuse, python-debian, markupsafe, license-expression, jinja2, chardet, attrs
#12 3.457 Successfully installed attrs-23.2.0 binaryornot-0.4.4 boolean-py-4.0 chardet-5.2.0 jinja2-3.1.4 license-expression-30.3.0 markupsafe-2.1.5 python-debian-0.1.49 reuse-4.0.3 tomlkit-0.13.0
#12 3.457 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#12 3.996 Collecting virtualenv
#12 4.061   Downloading virtualenv-20.31.2-py3-none-any.whl (6.1 MB)
#12 4.136      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.1/6.1 MB 82.7 MB/s eta 0:00:00
#12 4.196 Collecting platformdirs<5,>=3.9.1
#12 4.204   Downloading platformdirs-4.3.8-py3-none-any.whl (18 kB)
#12 4.244 Collecting filelock<4,>=3.12.2
#12 4.251   Downloading filelock-3.18.0-py3-none-any.whl (16 kB)
#12 4.272 Collecting distlib<1,>=0.3.7
#12 4.279   Downloading distlib-0.3.9-py2.py3-none-any.whl (468 kB)
#12 4.286      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 469.0/469.0 KB 94.3 MB/s eta 0:00:00
#12 4.367 Installing collected packages: distlib, platformdirs, filelock, virtualenv
#12 4.557 Successfully installed distlib-0.3.9 filelock-3.18.0 platformdirs-4.3.8 virtualenv-20.31.2
#12 4.557 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#12 DONE 4.6s

#13 [7/8] COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
#13 DONE 0.0s
---
DirectMap4k:      139200 kB
DirectMap2M:     7200768 kB
DirectMap1G:    11534336 kB
##[endgroup]
Executing TIDY_PRINT_DIFF=1 python2.7 ../x.py test            --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
+ TIDY_PRINT_DIFF=1 python2.7 ../x.py test --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
##[group]Building bootstrap
    Finished `dev` profile [unoptimized] target(s) in 0.05s
##[endgroup]
WARN: currently no CI rustc builds have rustc debug assertions enabled. Please either set `rust.debug-assertions` to `false` if you want to use download CI rustc or set `rust.download-rustc` to `false`.
WARN: `rust.debug-assertions = true` will prevent downloading CI rustc as alt CI rustc is not currently built with debug assertions.
---
fmt check
fmt: checked 6021 files
tidy check
tidy: Skipping binary file check, read-only filesystem
##[error]tidy error: /checkout/src/librustdoc/html/static/js/settings.js:357: line longer than 100 chars
removing old virtual environment
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'venv'
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'virtualenv'
Requirement already satisfied: pip in ./build/venv/lib/python3.10/site-packages (25.1.1)
linting python files
All checks passed!
checking python file formatting
26 files already formatted
checking C++ file formatting
some tidy checks failed
Command has failed. Rerun with -v to see more details.
Build completed unsuccessfully in 0:01:45
  local time: Tue May 20 16:25:52 UTC 2025
  network time: Tue, 20 May 2025 16:25:53 GMT
##[error]Process completed with exit code 1.
Post job cleanup.

[ojeda]

Thanks! This is the JS approach in the settings, nice. It is indeed simple.

Quick note: could we show /* private fields */ fields too? (I assume it doesn't affect those, but I didn't actually run it).

[ojeda]

Before I forget, "one more thing" that is probably out of scope but related to this toggle: we could consider having a way to write "private documentation", e.g. in the Linux kernel we sometimes have private invariants that we put currently in the documentation in their own section (# ...), but are really an implementation detail that ideally would go in a "private section of the docs". Using normal comments means we lose some features (e.g. nice rendered docs, intra-doc links, etc.), sadly. If we had that, this toggle could also show/hide that.

[lolbinarycat]

Quick note: could we show /* private fields */ fields too? (I assume it doesn't affect those, but I didn't actually run it).

yep, should be fairly simple, just another class and selector. currently private fields are always shown.

Before I forget, "one more thing" that is probably out of scope but related to this toggle: we could consider having a way to write "private documentation", e.g. in the Linux kernel we sometimes have private invariants that we put currently in the documentation in their own section (# ...), but are really an implementation detail that ideally would go in a "private section of the docs". Using normal comments means we lose some features (e.g. nice rendered docs, intra-doc links, etc.), sadly. If we had that, this toggle could also show/hide that.

generally this is done by putting doc comments on private items, but it should be doable with another css selector, as long as you don't mind writing an explicit html element with an explicit class.

[ojeda]

yep, should be fairly simple, just another class and selector. currently private fields are always shown.

That would be great to have, thanks!

generally this is done by putting doc comments on private items, but it should be doable with another css selector, as long as you don't mind writing an explicit html element with an explicit class.

These would be invariants on public items. I guess you mean moving everything into a new, private items? That I guess could work, but would be fairly complex just to add some private/implementation docs.

The HTML workaround seems OK; however, I was thinking more of having some kind of proper support for private documentation, e.g. something like:

/// Normal documentation.
///
/// My normal text.
//~
//~ # A private section
//~
//~ My private text.
pub struct S;

And then, within the private docs, one could refer to private fields with intra-doc links, too. Or even have doctests etc.