Skip to content

Commit

Permalink
Rollup merge of rust-lang#124011 - fmease:rustdoc-updated-clean-docs,…
Browse files Browse the repository at this point in the history
… r=GuillaumeGomez

rustdoc: update the module-level docs of `rustdoc::clean`

Let's update this 11-year-old documentation.
This would've helped me greatly when first starting out.

Please point out if I should add, clarify or correct anything.
I plan on looking through the rustc dev guide later to see if anything can be expanded upon over there, too.
  • Loading branch information
GuillaumeGomez committed Apr 16, 2024
2 parents dd08347 + a5a1775 commit f11b21b
Showing 1 changed file with 22 additions and 2 deletions.
24 changes: 22 additions & 2 deletions src/librustdoc/clean/mod.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,25 @@
//! This module contains the "cleaned" pieces of the AST, and the functions
//! that clean them.
//! This module defines the primary IR[^1] used in rustdoc together with the procedures that
//! transform rustc data types into it.
//!
//! This IR — commonly referred to as the *cleaned AST* — is modeled after the [AST][ast].
//!
//! There are two kinds of transformation — *cleaning* — procedures:
//!
//! 1. Cleans [HIR][hir] types. Used for user-written code and inlined local re-exports
//! both found in the local crate.
//! 2. Cleans [`rustc_middle::ty`] types. Used for inlined cross-crate re-exports and anything
//! output by the trait solver (e.g., when synthesizing blanket and auto-trait impls).
//! They usually have `ty` or `middle` in their name.
//!
//! Their name is prefixed by `clean_`.
//!
//! Both the HIR and the `rustc_middle::ty` IR are quite removed from the source code.
//! The cleaned AST on the other hand is closer to it which simplifies the rendering process.
//! Furthermore, operating on a single IR instead of two avoids duplicating efforts down the line.
//!
//! This IR is consumed by both the HTML and the JSON backend.
//!
//! [^1]: Intermediate representation.

mod auto_trait;
mod blanket_impl;
Expand Down

0 comments on commit f11b21b

Please sign in to comment.