From a5a1775c117e8238cc58b4db1ad8e731177795ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Le=C3=B3n=20Orell=20Valerian=20Liehr?= Date: Tue, 16 Apr 2024 13:26:51 +0200 Subject: [PATCH] rustdoc: update module-level docs of `rustdoc::clean` --- src/librustdoc/clean/mod.rs | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/src/librustdoc/clean/mod.rs b/src/librustdoc/clean/mod.rs index 925d41e67f8fa..fc4f48262e5dc 100644 --- a/src/librustdoc/clean/mod.rs +++ b/src/librustdoc/clean/mod.rs @@ -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;