Update docs from date triage for 2021-02 (#1048)

The biggest change was updating the list of rustdoc passes. Several new
ones have been added since that documentation was written, so I added
those, and I also sorted the list so it is roughly alphabetical (except
for the part for the `strip-*` passes, which I left in the same order
since one of the list items has two passes so there's no "correct"
order).

Author: camelid

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 <!-- date: 2020-08 -->, 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

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 <!-- date: 2020-04 -->, 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 <!-- date: 2021-02 -->, 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.

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 <!-- date: 2020-05 -->, 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 <!-- date: 2021-02 -->, 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

src/rustdoc-internals.md

@@ -51,44 +51,81 @@ 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
 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 <!-- date: 2018-03 -->:
+Here is the list of passes as of February 2021 <!-- date: 2021-02 -->:
+
+- `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 `<span>`)
+  in doc comments.
+
+- `check-non-autolinks` detects links that could or should be written using
+  angle brackets (the code behind the nightly-only <!-- date: 2021-02 -->
+  `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/
-

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 <!-- date:
-2018-02 -->, this includes compile-fail, run-fail, and incremental, though
+Certain classes of tests support "revisions" (as of February 2021 <!-- date:
+2021-02 -->, 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: