diff --git a/src/compiler-src.md b/src/compiler-src.md index 96e91fd73..c4f415441 100644 --- a/src/compiler-src.md +++ b/src/compiler-src.md @@ -21,10 +21,6 @@ containing the compiler, the standard libraries (`core`, `alloc`, `std`, `proc_macro`, etc), and `rustdoc`, along with the build system and a bunch of tools and submodules for building a full Rust distribution. -As of August 2020 , this structure is gradually undergoing -some transformation to make it a bit less monolithic and more approachable, -especially to newcomers. - The repository consists of three main directories: - `compiler/` contains the source code for `rustc`. It consists of many crates diff --git a/src/overview.md b/src/overview.md index 45ae0ab2e..c34d01dfd 100644 --- a/src/overview.md +++ b/src/overview.md @@ -250,9 +250,9 @@ Moreover, the compiler wasn't originally built to use a query system; the query system has been retrofitted into the compiler, so parts of it are not query-fied yet. Also, LLVM isn't our code, so that isn't querified either. The plan is to eventually query-fy all of the steps listed in the previous section, but as of -April 2020 , only the steps between HIR and LLVM-IR are -query-fied. That is, lexing and parsing are done all at once for the whole -program. +February 2021 , only the steps between HIR and LLVM IR are +query-fied. That is, lexing, parsing, name resolution, and macro expansion are +done all at once for the whole program. One other thing to mention here is the all-important "typing context", [`TyCtxt`], which is a giant struct that is at the center of all things. diff --git a/src/parallel-rustc.md b/src/parallel-rustc.md index 6f7f6f54b..c47a46e78 100644 --- a/src/parallel-rustc.md +++ b/src/parallel-rustc.md @@ -22,9 +22,9 @@ There are a few basic ideas in this effort: [`rayon`]: https://crates.io/crates/rayon -As of May 2020 , much of this effort is on hold due to -lack of manpower. We have a working prototype with promising performance gains -in many cases. However, there are two blockers: +As of February 2021 , much of this effort is on hold due +to lack of manpower. We have a working prototype with promising performance +gains in many cases. However, there are two blockers: - It's not clear what invariants need to be upheld that might not hold in the face of concurrency. An auditing effort was underway, but seems to have diff --git a/src/rustdoc-internals.md b/src/rustdoc-internals.md index 7460c012c..f7799f967 100644 --- a/src/rustdoc-internals.md +++ b/src/rustdoc-internals.md @@ -51,14 +51,14 @@ which describe the publicly-documentable items in the target crate. ### Hot potato Before moving on to the next major step, a few important "passes" occur over -the documentation. These do things like combine the separate "attributes" into +the documentation. These do things like combine the separate "attributes" into a single string and strip leading whitespace to make the document easier on the markdown parser, or drop items that are not public or deliberately hidden with `#[doc(hidden)]`. These are all implemented in the `passes/` directory, one file per pass. By default, all of these passes are run on a crate, but the ones regarding dropping private/hidden items can be bypassed by passing `--document-private-items` to rustdoc. Note that unlike the previous set of AST -transformations, the passes happen on the _cleaned_ crate. +transformations, the passes are run on the _cleaned_ crate. (Strictly speaking, you can fine-tune the passes run and even add your own, but [we're trying to deprecate that][44136]. If you need finer-grain control over @@ -66,29 +66,66 @@ these passes, please let us know!) [44136]: https://github.com/rust-lang/rust/issues/44136 -Here is the list of passes as of March 2018 : +Here is the list of passes as of February 2021 : + +- `calculate-doc-coverage` calculates information used for the `--show-coverage` + flag. + +- `check-code-block-syntax` validates syntax inside Rust code blocks + (`` ```rust ``) + +- `check-invalid-html-tags` detects invalid HTML (like an unclosed ``) + in doc comments. + +- `check-non-autolinks` detects links that could or should be written using + angle brackets (the code behind the nightly-only + `non_autolinks` lint). -- `propagate-doc-cfg` - propagates `#[doc(cfg(...))]` to child items. - `collapse-docs` concatenates all document attributes into one document attribute. This is necessary because each line of a doc comment is given as a separate doc attribute, and this will combine them into a single string with line breaks between each attribute. -- `unindent-comments` removes excess indentation on comments in order for - markdown to like it. This is necessary because the convention for writing - documentation is to provide a space between the `///` or `//!` marker and the - text, and stripping that leading space will make the text easier to parse by - the Markdown parser. (In the past, the markdown parser used was not - Commonmark- compliant, which caused annoyances with extra whitespace but this - seems to be less of an issue today.) + +- `collect-intra-doc-links` resolves [intra-doc links](https://doc.rust-lang.org/rustdoc/linking-to-items-by-name.html). + +- `collect-trait-impls` collects trait impls for each item in the crate. For + example, if we define a struct that implements a trait, this pass will note + that the struct implements that trait. + +- `doc-test-lints` runs various lints on the doctests. + +- `propagate-doc-cfg` propagates `#[doc(cfg(...))]` to child items. + - `strip-priv-imports` strips all private import statements (`use`, `extern crate`) from a crate. This is necessary because rustdoc will handle *public* imports by either inlining the item's documentation to the module or creating a "Reexports" section with the import in it. The pass ensures that all of these imports are actually relevant to documentation. + - `strip-hidden` and `strip-private` strip all `doc(hidden)` and private items from the output. `strip-private` implies `strip-priv-imports`. Basically, the goal is to remove items that are not relevant for public documentation. +- `unindent-comments` removes excess indentation on comments in order for the + Markdown to be parsed correctly. This is necessary because the convention for + writing documentation is to provide a space between the `///` or `//!` marker + and the doc text, but Markdown is whitespace-sensitive. For example, a block + of text with four-space indentation is parsed as a code block, so if we didn't + unindent comments, these list items + + ```rust,ignore + /// A list: + /// + /// - Foo + /// - Bar + ``` + + would be parsed as if they were in a code block, which is likely not what the + user intended. + +There is also a `stripper` module in `passes/`, but it is a collection of +utility functions for the `strip-*` passes and is not a pass itself. + ## From clean to crate This is where the "second phase" in rustdoc begins. This phase primarily lives @@ -224,4 +261,3 @@ on the internet. For example, the url for `std` will be `/std/". [`rustdoc` api docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/ [The rustdoc user guide]: https://doc.rust-lang.org/nightly/rustdoc/ - diff --git a/src/tests/adding.md b/src/tests/adding.md index c19271d2c..465317672 100644 --- a/src/tests/adding.md +++ b/src/tests/adding.md @@ -339,8 +339,8 @@ The error levels that you can have are: ## Revisions -Certain classes of tests support "revisions" (as of February 2018 , this includes compile-fail, run-fail, and incremental, though +Certain classes of tests support "revisions" (as of February 2021 , this includes compile-fail, run-fail, and incremental, though incremental tests are somewhat different). Revisions allow a single test file to be used for multiple tests. This is done by adding a special header at the top of the file: