Rustdoc 内部原理与开发实战从 Rust 编译器自带文档工具到 librustdoc 源码解析【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust本文基于 rustc-dev-guide 的 rustdoc.md 编写结合当前仓库源码深入展开。rustdoc 是随 Rust 编译器一起构建与发布的文档生成工具本文既覆盖从零搭建 rustdoc 开发环境、常用构建与测试命令的实战指南也深入剖析其编译到 HIR 后接管渲染的两阶段架构、代码模块地图与设计约束帮助读者快速上手 rustdoc 的开发与调试。概览rustdoc 与 rustc 同树共生rustdoc与编译器、标准库一起存放在同一个仓库中即当前仓库因此它的开发流程与rustc深度绑定。文档生成本身不依赖外部服务而是直接复用编译器的内部组件使用 rustc 内部 APIrustdoc 依赖rustcinternals以及标准库因此在构建 rustdoc 之前必须先构建一次编译器和std。整体实现位于librustdoccraterustdoc 的所有功能都实现在 src/librustdoc 这一个库 crate 中。运行到 HIR 阶段即接管rustdoc 把编译器驱动到已经得到 crate 的内部表示HIR且能够对 item 的类型执行部分查询的程度然后接管后续工作。HIR 与查询机制分别参见 hir.md 与 query.md。接管之后librustdoc分两大步骤完成一套文档的渲染Clean 阶段把 AST 清洗clean成更适合生成文档、同时对编译器内部变动更具抗性的形式。渲染阶段使用这份 cleaned AST逐页渲染 crate 的文档。当然实际流程比这复杂得多这两步只是对大量细节的高度概括但确实是理解整个 rustdoc 架构的高层主线。库 crate 与二进制的关系librustdoc是一个库 crate而rustdoc可执行文件由 src/tools/rustdoc 这个项目生成。关键在于该二进制几乎什么也没做只是调用librustdoc的lib.rs中定义的main()而已。查看 src/tools/rustdoc/main.rs 可以印证这一点// We need this feature as it changes dylib linking behavior and allows us to link to rustc_driver. #![feature(rustc_private)] extern crate rustc_driver; use std::process::ExitCode; // Override the C allocator in the same way that the rustc binary would do. rustc_driver::override_c_allocator_in_binary!(); fn main() - ExitCode { rustdoc::main() }而 src/librustdoc/lib.rs 通过大量extern crate直接链接rustc_abi、rustc_ast、rustc_driver、rustc_interface、rustc_middle等编译器 crate这些 crate 从 sysroot 隐式加载并声明了mod clean;、mod core;、mod doctest;、mod html;、mod markdown;等模块构成 rustdoc 的主体。从 HIR 到文档的两阶段核心流程librustdoc在拿到 HIR 与类型查询能力后执行两大步骤完成渲染对应源码中的两个关键模块Clean把编译器 IR 清洗为文档专用 AST清洗工作集中在 src/librustdoc/clean 目录数据类型定义在clean/types.rs这些是被渲染函数消费的文档模型例如Lifetime、Item等cleaned类型。转换函数实现在clean/mod.rs负责从HIR与rustc_middle::tyIR 创建上述数据类型的函数都集中在这里函数名以clean_开头每个函数接受一个hir或ty数据结构输出一个供 rustdoc 使用的clean结构。例如将 HIR 生命周期转换为 cleaned 生命周期的函数fn 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/mod.rs还定义了清洗后的 AST 类型用于后续渲染文档页面。大的 item如模块或关联项在clean函数中可能有额外处理但绝大多数impl都是直截了当的转换。该模块的入口是clean::utils::krate由run_global_ctxt调用其第一步是调用visit_ast::RustdocVisitor把模块树处理为中间的visit_ast::Module这一步真正爬取rustc_middle::hir::Crate并归一化名称解析的各种行为例如处理#[doc(inline)]与#[doc(no_inline)]处理 import glob 与循环避免重复或无限递归的目录树内联公有use对私有项的导出或在模块页展示 Reexport 行在基础 item 被隐藏时内联带#[doc(hidden)]的 item把#[macro_export]的宏展示在 crate 根无论其是否以 reexport 形式定义Render逐页渲染 cleaned AST渲染阶段消费 cleaned AST逐页输出 HTML。绝大多数 HTML 打印代码位于html/format.rs与html/render/mod.rs表现为一堆返回impl std::fmt::Display的函数见下文代码结构小节。开发速查表Cheat Sheetrustdoc 与编译器绑定因此推荐的开发入口是仓库根部的x工具./x或./x.py。以下是 rustdoc.md 提供的完整命令清单及说明初始化开发环境./x setup tools在开始开发前先运行此命令它会用适合开发 rustdoc 及其他工具的配置初始化x包括下载一份 rustc 副本而非自己编译从而显著加快开发迭代。快速检查编译错误./x check rustdoc用于快速检查 rustdoc 是否有编译错误适合频繁改代码时的快速反馈循环。构建可用的 rustdoc 并在其他项目上运行./x build library rustdoc构建出可在其他项目上运行的 rustdoc。补充说明追加library/test即可支持rustdoc --test文档测试功能构建完成后可把本地产物注册为 rustup 的自定义 toolchainrustup toolchain link stage2 build/host/stage2之后在任意目录下执行cargo stage2 doc就会用你本地编译出的 rustdoc 来生成文档。生成标准库文档./x doc library用本地构建的 rustdoc 生成标准库文档完整产物位于build/host/doc包含core、alloc、std等子目录若要把这些文档部署到 Web 服务器需要整体拷贝build/host/doc因为 CSS、JS、字体和落地页landing page都位于该目录前端调试时可关闭bootstrap.toml中的rust.docs-minification选项相关配置说明见 building/how-to-build-and-run.md避免文档被压缩混淆而难以调试。运行 rustdoc 测试./x test tests/rustdoc*使用 stage1 的 rustdoc 运行 rustdoc 相关测试。测试的更多细节参见 rustdoc-internals.md其中tests/compiletest.md#rustdoc-test-suites一节列出了 rustdoc 的测试套件划分。前端 JavaScript 检查./x test tidy --extra-checksjs显式运行 rustdoc 的 JavaScript 检查eslint、es-check与tsc。注意./x test tidy本身在 JS/TS 源文件发生变更时已经会自动运行这些检查--extra-checksjs只是强制显式执行。JavaScript CI 检查说明rustdoc 的前端 JavaScript 与 TypeScript 在 CI 中由eslint、es-check和tsc检查而非 compiletest它们作为tidyjob 的一部分运行./x test tidy --extra-checksjs--extra-checksjs标志启用 CI 中运行的前端 linting。代码结构地图以下路径均相对于仓库根目录展开原文档以src/librustdoc/为基准关注点源码位置大部分 HTML 打印代码src/librustdoc/html/format.rs 与 src/librustdoc/html/render/mod.rs由众多返回impl std::fmt::Display的函数构成被渲染的数据类型src/librustdoc/clean/types.rs从HIR与rustc_middle::tyIR 创建这些类型的函数在 src/librustdoc/clean/mod.rsrustdoc 作为测试框架doctest的专用逻辑src/librustdoc/doctest.rsMarkdown 渲染器src/librustdoc/html/markdown.rs包括从给定 Markdown 块中抽取 doctest 的函数前端 CSS 与 JavaScriptsrc/librustdoc/html/static关于前端 JavaScript 的特别说明rustdoc 前端使用TypeScript-flavored JSDoc 注释编写类型标注并配一份外部.d.ts文件。这样代码本身仍然是普通合法的 JavaScripttsc仅被用作 linter并不真正把前端代码编译为 TypeScript。测试体系rustdoc 的集成测试分散在多个测试套件中具体划分参见 tests/compiletest.md 中的 rustdoc 测试套件一节。结合速查表中的./x test tests/rustdoc*可以按前缀批量运行tests/rustdoc*覆盖 rustdoc 主体测试前端 JS/TS 由tidyjob 的 eslint / es-check / tsc 把关。设计约束rustdoc 的开发有一组明确的设计约束理解它们有助于避免在贡献时破坏现有行为。无 JavaScript 与本地文件支持rustdoc 努力在禁用 JavaScript以及浏览本地文件file:///URL两种场景下都保持可用并维护一份受支持的浏览器列表。支持本地文件带来了一些出人意料的限制某些依赖安全源secure origin的浏览器特性如localStorage与 Service Workers无法可靠工作。rustdoc 仍可使用这类特性但必须确保页面在缺少这些特性时依然可用。不类型检查函数体Type Checking of Function Bodiesrustdoc不完整类型检查函数体这一点通过以下机制组合实现对应源码 src/librustdoc/core.rs覆盖内置类型检查查询override queries在 core.rs 中rustdoc 通过override_queries回调注入自定义查询实现lint_mod被替换为只运行MissingDoc注释说明大多数 lint 需要类型检查所以干脆不运行它们used_trait_imports被替换为直接返回空集合的桩实现避免触发 typecktypeck_root被包装一层先通过EmitIgnoredResolutionErrors访问 body 并压制名称解析错误再调用默认查询提供者从而在发生名称解析错误时不会 ICE内部编译错误。压制名称解析错误让rustc_resolve在解析阶段容忍部分错误。不解析 opaque types避免触发需要类型检查 body 的路径。override_queries: Some(|_sess, providers| { // We do not register late module lints, so this only runs MissingDoc. // Most lints will require typechecking, so just dont run them. providers.queries.lint_mod |tcx, module_def_id| late_lint_mod(tcx, module_def_id, MissingDoc); // hack so that used_trait_imports wont try to call typeck providers.queries.used_trait_imports |_, _| { static EMPTY_SET: LazyLockUnordSetLocalDefId LazyLock::new(UnordSet::default); EMPTY_SET }; // In case typeck does end up being called, dont ICE in case there were name resolution errors providers.queries.typeck_root move |tcx, def_id| { assert!(!tcx.is_typeck_child(def_id.to_def_id())); let body tcx.hir_body_owned_by(def_id); debug!(visiting body for {def_id:?}); EmitIgnoredResolutionErrors::new(tcx).visit_body(body); (rustc_interface::DEFAULT_QUERY_PROVIDERS.queries.typeck_root)(tcx, def_id) }; }),这一模型带来若干重要后果rustdoc 无法运行任何需要类型检查函数体的编译器部分例如它不能生成.rlib文件也不能运行大多数 lint。需要说明的是这种接受不完全正确代码的模型并非 rustdoc 的理想终态。社区希望最终摆脱该模型但需要先为依赖它的用户例如平台特定文档场景下通过该机制使用#[cfg]处理不同目标文档、以及大量依赖文档中展示的代码无需完整通过类型检查的库找到替代方案。一个典型例子是tests/rustdoc-ui/error-in-impl-trait下的测试这些代码一旦移除该 hack 就会编译失败它们被用作该约束的回归测试。涉及此讨论的近期会议与 RFC 提案见 rustdoc 官方 Zulip 频道t-rustdoc meetings、t-compiler meetings 以及 stop accepting broken code 系列讨论。多次运行同一输出目录rustdoc 可以被多次调用、使用不同的输入而所有输出都写入同一个目录。这正是 cargo 为当前 crate 的依赖生成文档的方式也可以手动操作把关心的所有文档打包成一个大文档集合。HTML 是按 crate 独立生成的但目录中会累积一些跨 crate 信息随着向输出目录添加 crate 而不断更新cratesSUFFIX.js记录输出目录中所有 crate 的列表search-indexSUFFIX.js记录所有可搜索 item 的列表每个 trait 在implementors/.../trait.TraitName.js下有一个文件保存该 trait 的所有 implementorimplementor 可能与 trait 不在同一 crate随着发现新的 implementor该 JS 文件会被持续更新。这套机制是 docs.rs 与本地cargo doc得以把多 crate 文档合并进同一目录的基础。主要使用场景rustdoc 有若干必须牢记的主要使用场景任何对它的改动都应考虑对下列场景的影响标准库文档标准库文档作为 Rust 发布流程的一部分发布。稳定版还会上传到带版本号的 URLbeta 与 nightly 文档分别发布到对应渠道。发布通过 promote-release 工具完成并从 S3 经 CloudFront 提供服务。标准库文档包含5 个 cratealloc、core、proc_macro、std与test。docs.rs当 crate 发布到 crates.io 时docs.rs 会自动构建并发布其文档。docs.rs总是使用当前 nightly 的 rustdoc构建因此任何落地到 rustdoc 的改动都是瞬时稳定的——会立即对 docs.rs 上的公开页面产生影响。旧文档只偶尔重建所以浏览 docs.rs 上的旧版本时会看到 UI 的差异crate 作者可以请求重建重建会使用最新的 rustdoc 执行。docs.rs 会对 rustdoc 的输出做一些转换以节省存储并在顶部显示导航栏。具体而言某些静态文件如main.js和rustdoc.css可能在同版本 rustdoc 的多次调用间共享另一些如crates.js和sidebar-items.js则每次调用都不同还有一类如字体永远不会变化。这些类别通过src/librustdoc/html/render/write_shared.rs中的SharedResource枚举区分。此外docs.rs 上的文档每次只为一个 crate 生成因此搜索与侧边栏功能不包含当前 crate 的依赖。本地生成文档crate 作者可以在本地执行cargo doc --open查看自己 crate 的文档用来检查所写文档是否实用、显示是否正确非作者也可以用它查看想使用的 crate 的文档。两种情况都可能用到--document-private-items这个 Cargo 标志以查看默认不显示的私有方法、字段等。默认情况下cargo doc会为一个 crate及其所有依赖生成文档这可能产生非常庞大的文档包和又大又慢的搜索语料。Cargo 标志--no-deps可以抑制该行为只生成当前 crate 的文档。自托管项目文档一些项目自己托管文档本地生成文档后直接复制到 Web 服务器即可。rustdoc 的 HTML 输出可通过大量命令行标志高度定制——用户可以添加主题、设置默认主题、注入任意 HTML详见rustdoc --help的输出。小结rustdoc 是 Rust 工具链中与编译器同树共生的文档基础设施它以库 cratelibrustdoc为主体、src/tools/rustdoc中的二进制仅为薄壳核心工作流是编译至 HIR → clean 清洗 → 逐页渲染通过 override queries 等手段刻意回避对函数体的类型检查并面向标准库文档、docs.rs、本地cargo doc与自托管文档四大场景持续演进。掌握本文的环境搭建命令与源码地图即可开始为 rustdoc 贡献代码。【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Rustdoc 内部原理与开发实战：从 Rust 编译器自带文档工具到 librustdoc 源码解析
Rustdoc 内部原理与开发实战从 Rust 编译器自带文档工具到 librustdoc 源码解析【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust本文基于 rustc-dev-guide 的 rustdoc.md 编写结合当前仓库源码深入展开。rustdoc 是随 Rust 编译器一起构建与发布的文档生成工具本文既覆盖从零搭建 rustdoc 开发环境、常用构建与测试命令的实战指南也深入剖析其编译到 HIR 后接管渲染的两阶段架构、代码模块地图与设计约束帮助读者快速上手 rustdoc 的开发与调试。概览rustdoc 与 rustc 同树共生rustdoc与编译器、标准库一起存放在同一个仓库中即当前仓库因此它的开发流程与rustc深度绑定。文档生成本身不依赖外部服务而是直接复用编译器的内部组件使用 rustc 内部 APIrustdoc 依赖rustcinternals以及标准库因此在构建 rustdoc 之前必须先构建一次编译器和std。整体实现位于librustdoccraterustdoc 的所有功能都实现在 src/librustdoc 这一个库 crate 中。运行到 HIR 阶段即接管rustdoc 把编译器驱动到已经得到 crate 的内部表示HIR且能够对 item 的类型执行部分查询的程度然后接管后续工作。HIR 与查询机制分别参见 hir.md 与 query.md。接管之后librustdoc分两大步骤完成一套文档的渲染Clean 阶段把 AST 清洗clean成更适合生成文档、同时对编译器内部变动更具抗性的形式。渲染阶段使用这份 cleaned AST逐页渲染 crate 的文档。当然实际流程比这复杂得多这两步只是对大量细节的高度概括但确实是理解整个 rustdoc 架构的高层主线。库 crate 与二进制的关系librustdoc是一个库 crate而rustdoc可执行文件由 src/tools/rustdoc 这个项目生成。关键在于该二进制几乎什么也没做只是调用librustdoc的lib.rs中定义的main()而已。查看 src/tools/rustdoc/main.rs 可以印证这一点// We need this feature as it changes dylib linking behavior and allows us to link to rustc_driver. #![feature(rustc_private)] extern crate rustc_driver; use std::process::ExitCode; // Override the C allocator in the same way that the rustc binary would do. rustc_driver::override_c_allocator_in_binary!(); fn main() - ExitCode { rustdoc::main() }而 src/librustdoc/lib.rs 通过大量extern crate直接链接rustc_abi、rustc_ast、rustc_driver、rustc_interface、rustc_middle等编译器 crate这些 crate 从 sysroot 隐式加载并声明了mod clean;、mod core;、mod doctest;、mod html;、mod markdown;等模块构成 rustdoc 的主体。从 HIR 到文档的两阶段核心流程librustdoc在拿到 HIR 与类型查询能力后执行两大步骤完成渲染对应源码中的两个关键模块Clean把编译器 IR 清洗为文档专用 AST清洗工作集中在 src/librustdoc/clean 目录数据类型定义在clean/types.rs这些是被渲染函数消费的文档模型例如Lifetime、Item等cleaned类型。转换函数实现在clean/mod.rs负责从HIR与rustc_middle::tyIR 创建上述数据类型的函数都集中在这里函数名以clean_开头每个函数接受一个hir或ty数据结构输出一个供 rustdoc 使用的clean结构。例如将 HIR 生命周期转换为 cleaned 生命周期的函数fn 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/mod.rs还定义了清洗后的 AST 类型用于后续渲染文档页面。大的 item如模块或关联项在clean函数中可能有额外处理但绝大多数impl都是直截了当的转换。该模块的入口是clean::utils::krate由run_global_ctxt调用其第一步是调用visit_ast::RustdocVisitor把模块树处理为中间的visit_ast::Module这一步真正爬取rustc_middle::hir::Crate并归一化名称解析的各种行为例如处理#[doc(inline)]与#[doc(no_inline)]处理 import glob 与循环避免重复或无限递归的目录树内联公有use对私有项的导出或在模块页展示 Reexport 行在基础 item 被隐藏时内联带#[doc(hidden)]的 item把#[macro_export]的宏展示在 crate 根无论其是否以 reexport 形式定义Render逐页渲染 cleaned AST渲染阶段消费 cleaned AST逐页输出 HTML。绝大多数 HTML 打印代码位于html/format.rs与html/render/mod.rs表现为一堆返回impl std::fmt::Display的函数见下文代码结构小节。开发速查表Cheat Sheetrustdoc 与编译器绑定因此推荐的开发入口是仓库根部的x工具./x或./x.py。以下是 rustdoc.md 提供的完整命令清单及说明初始化开发环境./x setup tools在开始开发前先运行此命令它会用适合开发 rustdoc 及其他工具的配置初始化x包括下载一份 rustc 副本而非自己编译从而显著加快开发迭代。快速检查编译错误./x check rustdoc用于快速检查 rustdoc 是否有编译错误适合频繁改代码时的快速反馈循环。构建可用的 rustdoc 并在其他项目上运行./x build library rustdoc构建出可在其他项目上运行的 rustdoc。补充说明追加library/test即可支持rustdoc --test文档测试功能构建完成后可把本地产物注册为 rustup 的自定义 toolchainrustup toolchain link stage2 build/host/stage2之后在任意目录下执行cargo stage2 doc就会用你本地编译出的 rustdoc 来生成文档。生成标准库文档./x doc library用本地构建的 rustdoc 生成标准库文档完整产物位于build/host/doc包含core、alloc、std等子目录若要把这些文档部署到 Web 服务器需要整体拷贝build/host/doc因为 CSS、JS、字体和落地页landing page都位于该目录前端调试时可关闭bootstrap.toml中的rust.docs-minification选项相关配置说明见 building/how-to-build-and-run.md避免文档被压缩混淆而难以调试。运行 rustdoc 测试./x test tests/rustdoc*使用 stage1 的 rustdoc 运行 rustdoc 相关测试。测试的更多细节参见 rustdoc-internals.md其中tests/compiletest.md#rustdoc-test-suites一节列出了 rustdoc 的测试套件划分。前端 JavaScript 检查./x test tidy --extra-checksjs显式运行 rustdoc 的 JavaScript 检查eslint、es-check与tsc。注意./x test tidy本身在 JS/TS 源文件发生变更时已经会自动运行这些检查--extra-checksjs只是强制显式执行。JavaScript CI 检查说明rustdoc 的前端 JavaScript 与 TypeScript 在 CI 中由eslint、es-check和tsc检查而非 compiletest它们作为tidyjob 的一部分运行./x test tidy --extra-checksjs--extra-checksjs标志启用 CI 中运行的前端 linting。代码结构地图以下路径均相对于仓库根目录展开原文档以src/librustdoc/为基准关注点源码位置大部分 HTML 打印代码src/librustdoc/html/format.rs 与 src/librustdoc/html/render/mod.rs由众多返回impl std::fmt::Display的函数构成被渲染的数据类型src/librustdoc/clean/types.rs从HIR与rustc_middle::tyIR 创建这些类型的函数在 src/librustdoc/clean/mod.rsrustdoc 作为测试框架doctest的专用逻辑src/librustdoc/doctest.rsMarkdown 渲染器src/librustdoc/html/markdown.rs包括从给定 Markdown 块中抽取 doctest 的函数前端 CSS 与 JavaScriptsrc/librustdoc/html/static关于前端 JavaScript 的特别说明rustdoc 前端使用TypeScript-flavored JSDoc 注释编写类型标注并配一份外部.d.ts文件。这样代码本身仍然是普通合法的 JavaScripttsc仅被用作 linter并不真正把前端代码编译为 TypeScript。测试体系rustdoc 的集成测试分散在多个测试套件中具体划分参见 tests/compiletest.md 中的 rustdoc 测试套件一节。结合速查表中的./x test tests/rustdoc*可以按前缀批量运行tests/rustdoc*覆盖 rustdoc 主体测试前端 JS/TS 由tidyjob 的 eslint / es-check / tsc 把关。设计约束rustdoc 的开发有一组明确的设计约束理解它们有助于避免在贡献时破坏现有行为。无 JavaScript 与本地文件支持rustdoc 努力在禁用 JavaScript以及浏览本地文件file:///URL两种场景下都保持可用并维护一份受支持的浏览器列表。支持本地文件带来了一些出人意料的限制某些依赖安全源secure origin的浏览器特性如localStorage与 Service Workers无法可靠工作。rustdoc 仍可使用这类特性但必须确保页面在缺少这些特性时依然可用。不类型检查函数体Type Checking of Function Bodiesrustdoc不完整类型检查函数体这一点通过以下机制组合实现对应源码 src/librustdoc/core.rs覆盖内置类型检查查询override queries在 core.rs 中rustdoc 通过override_queries回调注入自定义查询实现lint_mod被替换为只运行MissingDoc注释说明大多数 lint 需要类型检查所以干脆不运行它们used_trait_imports被替换为直接返回空集合的桩实现避免触发 typecktypeck_root被包装一层先通过EmitIgnoredResolutionErrors访问 body 并压制名称解析错误再调用默认查询提供者从而在发生名称解析错误时不会 ICE内部编译错误。压制名称解析错误让rustc_resolve在解析阶段容忍部分错误。不解析 opaque types避免触发需要类型检查 body 的路径。override_queries: Some(|_sess, providers| { // We do not register late module lints, so this only runs MissingDoc. // Most lints will require typechecking, so just dont run them. providers.queries.lint_mod |tcx, module_def_id| late_lint_mod(tcx, module_def_id, MissingDoc); // hack so that used_trait_imports wont try to call typeck providers.queries.used_trait_imports |_, _| { static EMPTY_SET: LazyLockUnordSetLocalDefId LazyLock::new(UnordSet::default); EMPTY_SET }; // In case typeck does end up being called, dont ICE in case there were name resolution errors providers.queries.typeck_root move |tcx, def_id| { assert!(!tcx.is_typeck_child(def_id.to_def_id())); let body tcx.hir_body_owned_by(def_id); debug!(visiting body for {def_id:?}); EmitIgnoredResolutionErrors::new(tcx).visit_body(body); (rustc_interface::DEFAULT_QUERY_PROVIDERS.queries.typeck_root)(tcx, def_id) }; }),这一模型带来若干重要后果rustdoc 无法运行任何需要类型检查函数体的编译器部分例如它不能生成.rlib文件也不能运行大多数 lint。需要说明的是这种接受不完全正确代码的模型并非 rustdoc 的理想终态。社区希望最终摆脱该模型但需要先为依赖它的用户例如平台特定文档场景下通过该机制使用#[cfg]处理不同目标文档、以及大量依赖文档中展示的代码无需完整通过类型检查的库找到替代方案。一个典型例子是tests/rustdoc-ui/error-in-impl-trait下的测试这些代码一旦移除该 hack 就会编译失败它们被用作该约束的回归测试。涉及此讨论的近期会议与 RFC 提案见 rustdoc 官方 Zulip 频道t-rustdoc meetings、t-compiler meetings 以及 stop accepting broken code 系列讨论。多次运行同一输出目录rustdoc 可以被多次调用、使用不同的输入而所有输出都写入同一个目录。这正是 cargo 为当前 crate 的依赖生成文档的方式也可以手动操作把关心的所有文档打包成一个大文档集合。HTML 是按 crate 独立生成的但目录中会累积一些跨 crate 信息随着向输出目录添加 crate 而不断更新cratesSUFFIX.js记录输出目录中所有 crate 的列表search-indexSUFFIX.js记录所有可搜索 item 的列表每个 trait 在implementors/.../trait.TraitName.js下有一个文件保存该 trait 的所有 implementorimplementor 可能与 trait 不在同一 crate随着发现新的 implementor该 JS 文件会被持续更新。这套机制是 docs.rs 与本地cargo doc得以把多 crate 文档合并进同一目录的基础。主要使用场景rustdoc 有若干必须牢记的主要使用场景任何对它的改动都应考虑对下列场景的影响标准库文档标准库文档作为 Rust 发布流程的一部分发布。稳定版还会上传到带版本号的 URLbeta 与 nightly 文档分别发布到对应渠道。发布通过 promote-release 工具完成并从 S3 经 CloudFront 提供服务。标准库文档包含5 个 cratealloc、core、proc_macro、std与test。docs.rs当 crate 发布到 crates.io 时docs.rs 会自动构建并发布其文档。docs.rs总是使用当前 nightly 的 rustdoc构建因此任何落地到 rustdoc 的改动都是瞬时稳定的——会立即对 docs.rs 上的公开页面产生影响。旧文档只偶尔重建所以浏览 docs.rs 上的旧版本时会看到 UI 的差异crate 作者可以请求重建重建会使用最新的 rustdoc 执行。docs.rs 会对 rustdoc 的输出做一些转换以节省存储并在顶部显示导航栏。具体而言某些静态文件如main.js和rustdoc.css可能在同版本 rustdoc 的多次调用间共享另一些如crates.js和sidebar-items.js则每次调用都不同还有一类如字体永远不会变化。这些类别通过src/librustdoc/html/render/write_shared.rs中的SharedResource枚举区分。此外docs.rs 上的文档每次只为一个 crate 生成因此搜索与侧边栏功能不包含当前 crate 的依赖。本地生成文档crate 作者可以在本地执行cargo doc --open查看自己 crate 的文档用来检查所写文档是否实用、显示是否正确非作者也可以用它查看想使用的 crate 的文档。两种情况都可能用到--document-private-items这个 Cargo 标志以查看默认不显示的私有方法、字段等。默认情况下cargo doc会为一个 crate及其所有依赖生成文档这可能产生非常庞大的文档包和又大又慢的搜索语料。Cargo 标志--no-deps可以抑制该行为只生成当前 crate 的文档。自托管项目文档一些项目自己托管文档本地生成文档后直接复制到 Web 服务器即可。rustdoc 的 HTML 输出可通过大量命令行标志高度定制——用户可以添加主题、设置默认主题、注入任意 HTML详见rustdoc --help的输出。小结rustdoc 是 Rust 工具链中与编译器同树共生的文档基础设施它以库 cratelibrustdoc为主体、src/tools/rustdoc中的二进制仅为薄壳核心工作流是编译至 HIR → clean 清洗 → 逐页渲染通过 override queries 等手段刻意回避对函数体的类型检查并面向标准库文档、docs.rs、本地cargo doc与自托管文档四大场景持续演进。掌握本文的环境搭建命令与源码地图即可开始为 rustdoc 贡献代码。【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
