Rustdoc Limitations, Multiple Runs, and Use Cases

This comes with several caveats: in particular, rustdoc *cannot* run any parts of the compiler that require type-checking bodies; for example it cannot generate `.rlib` files or run most lints. We want to move away from this model eventually, but we need some alternative for [the people using it][async-std]; see [various][zulip stop accepting broken code] [previous][rustdoc meeting 2024-07-08] [zulip][compiler meeting 2023-01-26] [discussion][notriddle rfc]. For examples of code that breaks if this hack is removed, see [`tests/rustdoc-ui/error-in-impl-trait`]. ## Multiple runs, same output directory Rustdoc can be run multiple times for varying inputs, with its output set to the same directory. That's how cargo produces documentation for dependencies of the current crate. It can also be done manually if a user wants a big documentation bundle with all of the docs they care about. HTML is generated independently for each crate, but there is some cross-crate information that we update as we add crates to the output directory: - `crates<SUFFIX>.js` holds a list of all crates in the output directory. - `search-index<SUFFIX>.js` holds a list of all searchable items. - For each trait, there is a file under `implementors/.../trait.TraitName.js` containing a list of implementors of that trait. The implementors may be in different crates than the trait, and the JS file is updated as we discover new ones. ## Use cases There are a few major use cases for rustdoc that you should keep in mind when working on it: ### Standard library docs These are published at <https://doc.rust-lang.org/std> as part of the Rust release process. Stable releases are also uploaded to specific versioned URLs like <https://doc.rust-lang.org/1.57.0/std/>. Beta and nightly docs are published to <https://doc.rust-lang.org/beta/std/> and <https://doc.rust-lang.org/nightly/std/>. The docs are uploaded with the [promote-release tool](https://github.com/rust-lang/promote-release) and served from S3 with CloudFront. The standard library docs contain five crates: alloc, core, proc_macro, std, and test. ### docs.rs When crates are published to crates.io, docs.rs automatically builds and publishes their documentation, for instance at

This section discusses the limitations of Rustdoc, specifically its inability to perform type-checking on function bodies, which prevents it from generating `.rlib` files or running most lints. It explains the strategy to handle multiple Rustdoc runs with the same output directory, which is how Cargo generates documentation for dependencies and users can create large documentation bundles. It highlights the creation of `crates<SUFFIX>.js`, `search-index<SUFFIX>.js`, and trait implementor files. The section then covers the primary use cases for Rustdoc, including generating standard library documentation for doc.rust-lang.org and automatically generating documentation for crates published on crates.io through docs.rs.