Rustdoc Code Structure, Testing, Constraints, and Multiple Runs

* The types that got `Display` impls above are defined in `clean/mod.rs`, right next to the custom `Clean` trait used to process them out of the rustc HIR. * The bits specific to using rustdoc as a test harness are in `doctest.rs`. * The Markdown renderer is loaded up in `html/markdown.rs`, including functions for extracting doctests from a given block of Markdown. * Frontend CSS and JavaScript are stored in `html/static/`. ## Tests * Tests on search engine and index are located in `tests/rustdoc-js` and `tests/rustdoc-js-std`. The format is specified [in the search guide](rustdoc-internals/search.md#testing-the-search-engine). * Tests on the "UI" of rustdoc (the terminal output it produces when run) are in `tests/rustdoc-ui` * Tests on the "GUI" of rustdoc (the HTML, JS, and CSS as rendered in a browser) are in `tests/rustdoc-gui`. These use a [NodeJS tool called browser-UI-test](https://github.com/GuillaumeGomez/browser-UI-test/) that uses puppeteer to run tests in a headless browser and check rendering and interactivity. For information on how to write this form of test, see [`tests/rustdoc-gui/README.md`][rustdoc-gui-readme] as well as [the description of the `.goml` format][goml-script] * Tests on the structure of rustdoc HTML output are located in `tests/rustdoc`, where they're handled by the test runner of bootstrap and the supplementary script `src/etc/htmldocck.py`. [These tests have several extra directives available to them](./rustdoc-internals/rustdoc-test-suite.md). * Additionally, JavaScript type annotations are written using [TypeScript-flavored JSDoc] comments and an external d.ts file. The code itself is plain, valid JavaScript; we only use tsc as a linter. ## Constraints We try to make rustdoc work reasonably well with JavaScript disabled, and when browsing local files. We support [these browsers](https://rust-lang.github.io/rfcs/1985-tiered-browser-support.html#supported-browsers). Supporting local files (`file:///` URLs) brings some surprising restrictions. Certain browser features that require secure origins, like `localStorage` and Service Workers, don't work reliably. We can still use such features but we should make sure pages are still usable without them. Rustdoc [does not type-check function bodies][platform-specific docs]. This works by [overriding the built-in queries for typeck][override queries], by [silencing name resolution errors], and by [not resolving opaque types]. 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:

This section delves deeper into the code structure of Rustdoc, highlighting the locations of files related to Display implementations, the test harness, Markdown rendering, and frontend assets. It details the different types of tests used for Rustdoc, including those for search engine functionality, UI output, GUI rendering, and HTML structure, along with the tools and configurations required to run them. It also discusses the constraints Rustdoc operates under, such as browser compatibility and the need to function with JavaScript disabled, as well as the limitations due to not type-checking function bodies. The section concludes by explaining how Rustdoc handles multiple runs with the same output directory, which is crucial for generating documentation for crate dependencies.