尧图网站建设 
Rustdoc 内部机制详解从 crate 到 HTML 的两阶段管线与 Pass 架构【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust导读本文以 rust 仓库中src/doc/rustc-dev-guide/src/rustdoc-internals.md为骨架系统讲解rustdoc的核心内部机制它如何把一份 Rust crate 的 HIR 数据清洗clean成语义精炼的文档 AST再如何通过 Pass 管线与 HTML 渲染器逐页生成文档。读完本文你将掌握 rustdoc 的DocContext/run_global_ctxt入口、clean_*转换体系、--document-private-items等关键命令行标志的作用、Pass 的执行顺序与职责划分以及如何本地起 HTTP 服务验证生成的文档。rustdoc与编译器、标准库同树维护完全实现在librustdoc这个库 crate 中。rustdoc可执行文件本体位于 src/tools/rustdoc其全部工作只是调用该 cratelib.rs里的main()。它把编译器跑到拿到 crate 的内部表示HIR并能执行若干类型查询为止然后自己做两件大事把 AST 清洗clean成更适合生成文档、且对编译器内部变动更有抗性的形态用这份 cleaned AST 一页一页地渲染出整个 crate 的文档。本文后续所有路径均相对于仓库根目录展开。一、从 crate 到 clean文档清洗阶段1.1 两个核心载体DocContext与run_global_ctxt在 src/librustdoc/core.rs 里有两个中心角色DocContexttcxcore.rs爬取 crate 以收集文档时的状态容器。它持有tcx指针、当前参数环境param_env、外部 trait 集合external_traits、类型别名展开时的参数实例化映射args、自动 trait / blanket impl 合成去重集合以及贯穿整个 rustdoc 过程的共享缓存cache。run_global_ctxtcore.rsrustdoc 调用rustc把 crate 编译到rustdoc 可以接管的点的函数。它不调用tcx.analysis()因此不会对函数体做类型检查也不会跑默认的 rustc lint——这一点在 create_config 的override_queries中有明确体现lint_mod只跑MissingDocused_trait_imports被替换为空实现typeck_root被包上一层EmitIgnoredResolutionErrors以便在解析错误存在时不至于 ICE。run_global_ctxt的流程大致为先做宏展开的源码记录source_macro_expansion再跑wf_checking、missing_docs、check_mod_attrs等检查收集可见的 auto trait构建DocContext最后调用clean::krate(mut ctxt)进入清洗阶段随后执行 Pass 管线见下文第二节填充Cache最终返回(clean::Crate, RenderOptions, Cache, …)。1.2clean_*函数族HIR/ty 到 clean AST 的转换crate 爬取的主流程在 src/librustdoc/clean/mod.rs 中由一批名字以clean_开头的函数完成。每个函数接收一个hir或ty数据结构输出一个 rustdoc 使用的 clean 结构。以生命周期转换函数为例clean/mod.rsfn clean_lifetimetcx(lifetime: hir::Lifetime, cx: mut DocContexttcx) - Lifetime { if let Some( rbv::ResolvedArg::EarlyBound(did) | rbv::ResolvedArg::LateBound(_, _, did) | rbv::ResolvedArg::Free(_, did), ) cx.tcx.named_bound_var(lifetime.hir_id) let Some(lt) cx.args.get(did).and_then(|arg| arg.as_lt()) { return lt.clone(); } Lifetime(lifetime.ident.name) }这段代码展示了 clean 转换的典型思路优先查询tcx.named_bound_var判断生命周期是否为已解析的泛型参数若是则从DocContext.args类型别名展开的当前参数实例化中取回替换后的生命周期否则退回使用其标识符名。同时clean/mod.rs 还定义了清洗后的 AST 类型如Item、Type、Lifetime等详见 clean/types.rs每个类型通常伴随一个从 rustc 的 AST/HIR 类型转换而来的clean_*函数。大件条目如模块、关联项可能在 clean 函数里有额外处理但大部分 impl 都是直截了当的转换。该模块的入口是clean::utils::krate由run_global_ctxt调用。1.3clean::utils::krate先访问模块树再深度清洗clean::utils::krate的第一步是调用visit_ast::RustdocVisitor把模块树处理成中间的visit_ast::Module。这一步才是真正爬取rustc_middle::hir::Crate的地方它会规范化名称解析的各种情况处理#[doc(inline)]与#[doc(no_inline)]处理导入通配符glob与循环避免出现重复或无限递归的目录树对公开use导出的私有项进行内联或在模块页显示 Reexport 行当基础条目被隐藏时内联#[doc(hidden)]条目无论#[macro_export]宏是以 reexport 还是其他方式定义都在 crate 根展示它。在 visit_ast.rs 中可以看到pub use目标的解析与内联逻辑它会先检查#[doc(no_inline)]属性find_attr!宏查找命中则记录为普通 import否则尝试解析目标并把外部条目放进inlined_foreigns等待内联。第二步clean::krate调用clean_doc_module把 HIR 条目真正转换成 cleaned AST。这一步同时完成跨 crate 内联cross-crate inlining——它需要把rustc_middle的数据结构转换成 cleaned AST。clean_doc_module 中可以看到模块条目的组织方式先处理 extern 项再处理子模块递归然后拆分 glob 导入与其他条目最后统一处理use语句。此外clean/mod.rs中另一件大事是把文档注释与#[doc]属性收集进Attributes结构体的独立字段凡是手写文档的条目都会带上便于流程后期统一收集。这一阶段的主要产物是clean::types::Crate其中包含一棵描述目标 crate 所有可公开文档化条目的Item树。二、Pass 管线Anything But a Gas Station在进入渲染之前会对 cleaned AST 运行一批重要的 pass。其中一些是 lint 与报告另一些会修改或生成新的条目。它们全部实现在 src/librustdoc/passes 目录下每个 pass 一个文件。默认情况下所有 pass 都会对 crate 运行但丢弃私有/隐藏条目的 pass 可以通过向 rustdoc 传--document-private-items来绕过。注意与前面那批 AST 转换不同pass 运行在清洗后的crate 之上。passes/mod.rs 中的run函数给出了真实的执行顺序show_coverage为假时collect_trait_impls→check_doc_test_visibility→strip_aliased_non_local→propagate_doc_cfg→strip_hidden→strip_private→strip_priv_imports→collect_intra_doc_links→propagate_stability→lint。文档编写于 2023 年 3 月下面按文档口径逐一说明Pass职责相关命令行标志calculate-doc-coverage计算--show-coverage标志所需的信息--show-coveragecheck-doc-test-visibility运行 doctest 可见性相关 lint必须在strip-private之前运行—collect-intra-doc-links解析 intra-doc links—collect-trait-impls收集 crate 中每个条目的 trait impl例如某struct实现了某traitpass 会记下这一对应关系—propagate-doc-cfg把#[doc(cfg(...))]传播给子条目—run-lints运行passes/lint中定义的 rustdoc lint是最后运行的 pass—strip-hidden/strip-private从输出中剥离所有doc(hidden)与私有条目strip-private隐含strip-priv-imports传--document-hidden-items时跳过--document-hidden-itemsstrip-priv-imports剥离 crate 中所有私有导入use、extern crate技术上只在传--document-private-items时运行但strip-private已达成同样效果--document-private-itemsstrip-private剥离所有外部不可见的私有条目传--document-private-items时跳过--document-private-itemsrun-lints名下还有几个具体的 lint定义于 passes/lint.rs 与 passes/lint 子目录bare_urls检测未被链接化的链接例如 Markdown 中的Go to https://example.com/.建议写成Go to https://example.com/.使其成为链接。这是rustdoc::bare_urlslint 背后的实现2022 年 5 月标注。check_code_block_syntax校验 rust 代码块内的 Rust 语法。html_tags检测文档注释中无效的 HTML如未闭合的span。另外passes/stripper.rs 不是 pass 本身而是strip-*系列 pass 共享的工具函数集合。Pass 结束后passes::finalize会调用collect_intra_doc_links::resolve_ambiguous_links处理歧义链接。三、从 clean 到 HTML渲染阶段3.1run_format与FormatRenderertrait这是 rustdoc 的第二阶段主要位于 src/librustdoc/formats 与 src/librustdoc/html 目录起点是formats::renderer::run_format。这段代码负责搭建一个impl FormatRenderer的类型——对 HTML 来说就是Context。FormatRenderertrait 定义了驱动文档渲染的钩子init生成static.files以及搜索索引和src/目录item生成条目 HTML 文件本身after_krate生成其他全局资源如all.html。run_format_inner递归处理模块树遇到模块时调用mod_item_in随后对每个子条目执行save_module_data→item→restore_module_data防止子模块污染兄弟条目的渲染状态最后mod_item_out。这也解释了FormatRenderer::ModuleData关联类型的作用。3.2 页面渲染Askama 模板 fmt::Display在item中发生页面渲染方式是 Askama 开始。尚未模板化的部分位于一系列std::fmt::Display实现和传递mut std::fmt::Formatter的函数中。真正从条目与文档生成 HTML 的部分从print_item开始它根据被渲染Item的种类切换到多个item_*函数之一。按你查找的渲染代码不同主要条目的struct 页该打印哪些 section这类逻辑在 html/render/mod.rswhere 子句作为其他条目一部分如何打印这类小组件在 html/format.rs。每当 rustdoc 遇到需要把手写文档打印出来的条目时它会调用 html/markdown.rs由它对接 Markdown 解析器。这里以一系列包装字符串的fmt::Display类型对外暴露并在运行 Markdown 解析器之前特别开启脚注、表格等特性并经由 html/highlight.rs 给 Rust 代码块加语法高亮。此外还有find_codes函数被find_testable_codes调用专门扫描 Rust 代码块好让测试运行器找到 crate 里所有 doctest。3.3Context与SharedContext为多线程做准备的数据切分html::render::context::{Context, SharedContext}这两个类型context.rs把 rustdoc 的数据分为两类既为了将来多线程文档生成做准备也为了保持条理Context保存生成当前页面所需的数据如当前路径、已用过的 HTML ID 列表避免重复id以及指向SharedContext的指针。它是一个轻量对象会被克隆到每个工作单元约每渲染一个条目克隆一次。SharedContext保存不随页面变化的数据如tcx指针、所有类型的列表等。3.4 关键设计约束为什么 clean AST 是公共输出格式值得注意rustdoc 现在可以把TyCtxt直接传给formats::renderer::run_format在 HTML 生成期间直接向编译器询问类型信息这在历史上是做不到的早期 rustdoc 的很多架构都刻意回避了这一点该TyCtxt同时用于 HTML 与截至 2026 年 5 月仍不稳定的JSON 输出。这一变化允许把 clean AST 中那些容易从TyCtxt查询推导出来的数据移除rustdoc 社区通常也会接受移除 clean 字段的 PRclean 已被软弃用但这受制于两个约束文档可以为未通过类型检查的 crate 生成例如libstd需要一份覆盖所有受支持操作系统的文档包这意味着 rustdoc 必须能仅从 HIR 生成文档文档可以跨 crate 内联crate 元数据不含 HIR因此必须能仅从rustc_middle数据生成内联文档。clean AST 正是这两种输入格式的公共输出格式。此外clean 里还有不直接对应 HIR 的数据例如collect-trait-implspass 为 auto trait 和 blanket impl 合成的impl对应源码 clean/auto_trait.rs 与 clean/blanket_impl.rs 的synthesize_auto_trait_impls/synthesize_blanket_impls。四、其他运行模式独立 Markdown 与 doctest以上描述的是从 Rust crate 生成 HTML 文档的流程但 rustdoc 还有两种主要运行模式对独立 Markdown 文件运行以及对 Rust 代码或独立 Markdown 文件运行 doctest。独立 Markdown 模式直接抄近路进入html/markdown.rs可选用一种往输出 HTML 里插入目录Table of Contents的模式。doctest 模式下rustdoc 在 doctest.rs 中做一次类似的部分编译以拿到相关文档但不走完整的 clean 与渲染流程而是跑一个更简单的 crate 遍历只抓取手写文档。再配合前述 html/markdown.rs 的find_testable_code收集全部待运行测试后交给测试运行器。其中一个值得关注的函数是 doctest/make.rs 中的make_test——手写的 doctest 正是在这里被改造成可执行代码它处理 crate 级代码注入例如隐式extern crate r#{crate_name};并加#[allow(unused_extern_crates)]、为测试生成唯一命名的main函数包装如_doctest_main_{test_id}支持-C instrument-coverage、处理Result返回值的 unwrap 以及no_std等特殊情况。对独立 Markdown 文件运行 doctest 的入口则是 doctest/markdown.rs 的test函数。五、本地测试起一个 HTTP 服务器查看文档生成 HTML 文档的某些特性需要跨页面使用本地存储没有 HTTP 服务器时效果不佳。要本地测试这些特性可以这样$ ./x doc library # 文档已生成到 build/[YOUR ARCH]/doc $ python3 -m http.server -d build/[YOUR ARCH]/doc之后就能像访问线上文档一样浏览例如std的 URL 是rust/std/。补充说明来自 rustdoc 概览开发 rustdoc 时可用./x setup tools配置开发环境./x check rustdoc快速检查编译错误./x build library rustdoc构建可用的 rustdocrustup toolchain link stage2 build/host/stage2注册本地 toolchain 后用cargo stage2 doc验证完整文档会输出在build/host/doc含core、alloc、std前端调试时可关闭rust.docs-minification选项。六、延伸阅读Rustdoc 概览rustdoc 的总体介绍、速查表与代码结构rustdoc 用户指南功能与使用方法的权威说明rustdoc API 文档DocContext、run_global_ctxt、clean等内部 API 的 rustdoc 化文档核心源码入口core.rsDocContext/run_global_ctxt、clean/mod.rsclean_*函数族、passes/mod.rsPass 调度、formats/renderer.rs渲染调度、html/render/print_item.rs页面渲染、doctest/make.rsdoctest 生成【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rustdoc 内部机制详解：从 crate 到 HTML 的两阶段管线与 Pass 架构
Rustdoc 内部机制详解从 crate 到 HTML 的两阶段管线与 Pass 架构【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust导读本文以 rust 仓库中src/doc/rustc-dev-guide/src/rustdoc-internals.md为骨架系统讲解rustdoc的核心内部机制它如何把一份 Rust crate 的 HIR 数据清洗clean成语义精炼的文档 AST再如何通过 Pass 管线与 HTML 渲染器逐页生成文档。读完本文你将掌握 rustdoc 的DocContext/run_global_ctxt入口、clean_*转换体系、--document-private-items等关键命令行标志的作用、Pass 的执行顺序与职责划分以及如何本地起 HTTP 服务验证生成的文档。rustdoc与编译器、标准库同树维护完全实现在librustdoc这个库 crate 中。rustdoc可执行文件本体位于 src/tools/rustdoc其全部工作只是调用该 cratelib.rs里的main()。它把编译器跑到拿到 crate 的内部表示HIR并能执行若干类型查询为止然后自己做两件大事把 AST 清洗clean成更适合生成文档、且对编译器内部变动更有抗性的形态用这份 cleaned AST 一页一页地渲染出整个 crate 的文档。本文后续所有路径均相对于仓库根目录展开。一、从 crate 到 clean文档清洗阶段1.1 两个核心载体DocContext与run_global_ctxt在 src/librustdoc/core.rs 里有两个中心角色DocContexttcxcore.rs爬取 crate 以收集文档时的状态容器。它持有tcx指针、当前参数环境param_env、外部 trait 集合external_traits、类型别名展开时的参数实例化映射args、自动 trait / blanket impl 合成去重集合以及贯穿整个 rustdoc 过程的共享缓存cache。run_global_ctxtcore.rsrustdoc 调用rustc把 crate 编译到rustdoc 可以接管的点的函数。它不调用tcx.analysis()因此不会对函数体做类型检查也不会跑默认的 rustc lint——这一点在 create_config 的override_queries中有明确体现lint_mod只跑MissingDocused_trait_imports被替换为空实现typeck_root被包上一层EmitIgnoredResolutionErrors以便在解析错误存在时不至于 ICE。run_global_ctxt的流程大致为先做宏展开的源码记录source_macro_expansion再跑wf_checking、missing_docs、check_mod_attrs等检查收集可见的 auto trait构建DocContext最后调用clean::krate(mut ctxt)进入清洗阶段随后执行 Pass 管线见下文第二节填充Cache最终返回(clean::Crate, RenderOptions, Cache, …)。1.2clean_*函数族HIR/ty 到 clean AST 的转换crate 爬取的主流程在 src/librustdoc/clean/mod.rs 中由一批名字以clean_开头的函数完成。每个函数接收一个hir或ty数据结构输出一个 rustdoc 使用的 clean 结构。以生命周期转换函数为例clean/mod.rsfn clean_lifetimetcx(lifetime: hir::Lifetime, cx: mut DocContexttcx) - Lifetime { if let Some( rbv::ResolvedArg::EarlyBound(did) | rbv::ResolvedArg::LateBound(_, _, did) | rbv::ResolvedArg::Free(_, did), ) cx.tcx.named_bound_var(lifetime.hir_id) let Some(lt) cx.args.get(did).and_then(|arg| arg.as_lt()) { return lt.clone(); } Lifetime(lifetime.ident.name) }这段代码展示了 clean 转换的典型思路优先查询tcx.named_bound_var判断生命周期是否为已解析的泛型参数若是则从DocContext.args类型别名展开的当前参数实例化中取回替换后的生命周期否则退回使用其标识符名。同时clean/mod.rs 还定义了清洗后的 AST 类型如Item、Type、Lifetime等详见 clean/types.rs每个类型通常伴随一个从 rustc 的 AST/HIR 类型转换而来的clean_*函数。大件条目如模块、关联项可能在 clean 函数里有额外处理但大部分 impl 都是直截了当的转换。该模块的入口是clean::utils::krate由run_global_ctxt调用。1.3clean::utils::krate先访问模块树再深度清洗clean::utils::krate的第一步是调用visit_ast::RustdocVisitor把模块树处理成中间的visit_ast::Module。这一步才是真正爬取rustc_middle::hir::Crate的地方它会规范化名称解析的各种情况处理#[doc(inline)]与#[doc(no_inline)]处理导入通配符glob与循环避免出现重复或无限递归的目录树对公开use导出的私有项进行内联或在模块页显示 Reexport 行当基础条目被隐藏时内联#[doc(hidden)]条目无论#[macro_export]宏是以 reexport 还是其他方式定义都在 crate 根展示它。在 visit_ast.rs 中可以看到pub use目标的解析与内联逻辑它会先检查#[doc(no_inline)]属性find_attr!宏查找命中则记录为普通 import否则尝试解析目标并把外部条目放进inlined_foreigns等待内联。第二步clean::krate调用clean_doc_module把 HIR 条目真正转换成 cleaned AST。这一步同时完成跨 crate 内联cross-crate inlining——它需要把rustc_middle的数据结构转换成 cleaned AST。clean_doc_module 中可以看到模块条目的组织方式先处理 extern 项再处理子模块递归然后拆分 glob 导入与其他条目最后统一处理use语句。此外clean/mod.rs中另一件大事是把文档注释与#[doc]属性收集进Attributes结构体的独立字段凡是手写文档的条目都会带上便于流程后期统一收集。这一阶段的主要产物是clean::types::Crate其中包含一棵描述目标 crate 所有可公开文档化条目的Item树。二、Pass 管线Anything But a Gas Station在进入渲染之前会对 cleaned AST 运行一批重要的 pass。其中一些是 lint 与报告另一些会修改或生成新的条目。它们全部实现在 src/librustdoc/passes 目录下每个 pass 一个文件。默认情况下所有 pass 都会对 crate 运行但丢弃私有/隐藏条目的 pass 可以通过向 rustdoc 传--document-private-items来绕过。注意与前面那批 AST 转换不同pass 运行在清洗后的crate 之上。passes/mod.rs 中的run函数给出了真实的执行顺序show_coverage为假时collect_trait_impls→check_doc_test_visibility→strip_aliased_non_local→propagate_doc_cfg→strip_hidden→strip_private→strip_priv_imports→collect_intra_doc_links→propagate_stability→lint。文档编写于 2023 年 3 月下面按文档口径逐一说明Pass职责相关命令行标志calculate-doc-coverage计算--show-coverage标志所需的信息--show-coveragecheck-doc-test-visibility运行 doctest 可见性相关 lint必须在strip-private之前运行—collect-intra-doc-links解析 intra-doc links—collect-trait-impls收集 crate 中每个条目的 trait impl例如某struct实现了某traitpass 会记下这一对应关系—propagate-doc-cfg把#[doc(cfg(...))]传播给子条目—run-lints运行passes/lint中定义的 rustdoc lint是最后运行的 pass—strip-hidden/strip-private从输出中剥离所有doc(hidden)与私有条目strip-private隐含strip-priv-imports传--document-hidden-items时跳过--document-hidden-itemsstrip-priv-imports剥离 crate 中所有私有导入use、extern crate技术上只在传--document-private-items时运行但strip-private已达成同样效果--document-private-itemsstrip-private剥离所有外部不可见的私有条目传--document-private-items时跳过--document-private-itemsrun-lints名下还有几个具体的 lint定义于 passes/lint.rs 与 passes/lint 子目录bare_urls检测未被链接化的链接例如 Markdown 中的Go to https://example.com/.建议写成Go to https://example.com/.使其成为链接。这是rustdoc::bare_urlslint 背后的实现2022 年 5 月标注。check_code_block_syntax校验 rust 代码块内的 Rust 语法。html_tags检测文档注释中无效的 HTML如未闭合的span。另外passes/stripper.rs 不是 pass 本身而是strip-*系列 pass 共享的工具函数集合。Pass 结束后passes::finalize会调用collect_intra_doc_links::resolve_ambiguous_links处理歧义链接。三、从 clean 到 HTML渲染阶段3.1run_format与FormatRenderertrait这是 rustdoc 的第二阶段主要位于 src/librustdoc/formats 与 src/librustdoc/html 目录起点是formats::renderer::run_format。这段代码负责搭建一个impl FormatRenderer的类型——对 HTML 来说就是Context。FormatRenderertrait 定义了驱动文档渲染的钩子init生成static.files以及搜索索引和src/目录item生成条目 HTML 文件本身after_krate生成其他全局资源如all.html。run_format_inner递归处理模块树遇到模块时调用mod_item_in随后对每个子条目执行save_module_data→item→restore_module_data防止子模块污染兄弟条目的渲染状态最后mod_item_out。这也解释了FormatRenderer::ModuleData关联类型的作用。3.2 页面渲染Askama 模板 fmt::Display在item中发生页面渲染方式是 Askama 开始。尚未模板化的部分位于一系列std::fmt::Display实现和传递mut std::fmt::Formatter的函数中。真正从条目与文档生成 HTML 的部分从print_item开始它根据被渲染Item的种类切换到多个item_*函数之一。按你查找的渲染代码不同主要条目的struct 页该打印哪些 section这类逻辑在 html/render/mod.rswhere 子句作为其他条目一部分如何打印这类小组件在 html/format.rs。每当 rustdoc 遇到需要把手写文档打印出来的条目时它会调用 html/markdown.rs由它对接 Markdown 解析器。这里以一系列包装字符串的fmt::Display类型对外暴露并在运行 Markdown 解析器之前特别开启脚注、表格等特性并经由 html/highlight.rs 给 Rust 代码块加语法高亮。此外还有find_codes函数被find_testable_codes调用专门扫描 Rust 代码块好让测试运行器找到 crate 里所有 doctest。3.3Context与SharedContext为多线程做准备的数据切分html::render::context::{Context, SharedContext}这两个类型context.rs把 rustdoc 的数据分为两类既为了将来多线程文档生成做准备也为了保持条理Context保存生成当前页面所需的数据如当前路径、已用过的 HTML ID 列表避免重复id以及指向SharedContext的指针。它是一个轻量对象会被克隆到每个工作单元约每渲染一个条目克隆一次。SharedContext保存不随页面变化的数据如tcx指针、所有类型的列表等。3.4 关键设计约束为什么 clean AST 是公共输出格式值得注意rustdoc 现在可以把TyCtxt直接传给formats::renderer::run_format在 HTML 生成期间直接向编译器询问类型信息这在历史上是做不到的早期 rustdoc 的很多架构都刻意回避了这一点该TyCtxt同时用于 HTML 与截至 2026 年 5 月仍不稳定的JSON 输出。这一变化允许把 clean AST 中那些容易从TyCtxt查询推导出来的数据移除rustdoc 社区通常也会接受移除 clean 字段的 PRclean 已被软弃用但这受制于两个约束文档可以为未通过类型检查的 crate 生成例如libstd需要一份覆盖所有受支持操作系统的文档包这意味着 rustdoc 必须能仅从 HIR 生成文档文档可以跨 crate 内联crate 元数据不含 HIR因此必须能仅从rustc_middle数据生成内联文档。clean AST 正是这两种输入格式的公共输出格式。此外clean 里还有不直接对应 HIR 的数据例如collect-trait-implspass 为 auto trait 和 blanket impl 合成的impl对应源码 clean/auto_trait.rs 与 clean/blanket_impl.rs 的synthesize_auto_trait_impls/synthesize_blanket_impls。四、其他运行模式独立 Markdown 与 doctest以上描述的是从 Rust crate 生成 HTML 文档的流程但 rustdoc 还有两种主要运行模式对独立 Markdown 文件运行以及对 Rust 代码或独立 Markdown 文件运行 doctest。独立 Markdown 模式直接抄近路进入html/markdown.rs可选用一种往输出 HTML 里插入目录Table of Contents的模式。doctest 模式下rustdoc 在 doctest.rs 中做一次类似的部分编译以拿到相关文档但不走完整的 clean 与渲染流程而是跑一个更简单的 crate 遍历只抓取手写文档。再配合前述 html/markdown.rs 的find_testable_code收集全部待运行测试后交给测试运行器。其中一个值得关注的函数是 doctest/make.rs 中的make_test——手写的 doctest 正是在这里被改造成可执行代码它处理 crate 级代码注入例如隐式extern crate r#{crate_name};并加#[allow(unused_extern_crates)]、为测试生成唯一命名的main函数包装如_doctest_main_{test_id}支持-C instrument-coverage、处理Result返回值的 unwrap 以及no_std等特殊情况。对独立 Markdown 文件运行 doctest 的入口则是 doctest/markdown.rs 的test函数。五、本地测试起一个 HTTP 服务器查看文档生成 HTML 文档的某些特性需要跨页面使用本地存储没有 HTTP 服务器时效果不佳。要本地测试这些特性可以这样$ ./x doc library # 文档已生成到 build/[YOUR ARCH]/doc $ python3 -m http.server -d build/[YOUR ARCH]/doc之后就能像访问线上文档一样浏览例如std的 URL 是rust/std/。补充说明来自 rustdoc 概览开发 rustdoc 时可用./x setup tools配置开发环境./x check rustdoc快速检查编译错误./x build library rustdoc构建可用的 rustdocrustup toolchain link stage2 build/host/stage2注册本地 toolchain 后用cargo stage2 doc验证完整文档会输出在build/host/doc含core、alloc、std前端调试时可关闭rust.docs-minification选项。六、延伸阅读Rustdoc 概览rustdoc 的总体介绍、速查表与代码结构rustdoc 用户指南功能与使用方法的权威说明rustdoc API 文档DocContext、run_global_ctxt、clean等内部 API 的 rustdoc 化文档核心源码入口core.rsDocContext/run_global_ctxt、clean/mod.rsclean_*函数族、passes/mod.rsPass 调度、formats/renderer.rs渲染调度、html/render/print_item.rs页面渲染、doctest/make.rsdoctest 生成【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考