Back to Details

rustdoc-library-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Rustdoc Library Documentation

Rustdoc 库文档

Use this skill to make Rust library documentation executable, navigable, and useful to downstream crate consumers.
使用本技能可让Rust库文档具备可执行性、易导航性，且对下游crate使用者更实用。

Core Workflow

核心工作流程

  1. Start from the consumer's first task, not from internal module order.
  2. Add crate-level and module-level docs that explain purpose and boundaries.
  3. Document public types, functions, errors, features, and invariants.
  4. Prefer short compiling examples and doctests for core APIs.
  5. Put longer scenarios in 
    examples/
    and reference them from docs.
  6. Run docs and doctests before publishing.
  1. 从使用者的首要需求出发，而非按照内部模块顺序编写。
  2. 添加 crate 级和模块级文档，说明其用途与适用范围。
  3. 为公共类型、函数、错误、特性以及不变量添加文档说明。
  4. 核心API优先使用可编译的简短示例和文档测试（doctests）。
  5. 将较长的场景示例放在
    examples/
    目录中，并在文档中引用它们。
  6. 发布前运行文档和文档测试。

Read Next

后续任务

TaskLoad
Document a public crate API
guidelines.md
, 
workflows/document-library.md
Add doctests or examples
references/rustdoc-patterns.md
Prepare docs for publishing
references/rustdoc-patterns.md
任务参考文档
编写公共crate API文档
guidelines.md
, 
workflows/document-library.md
添加文档测试或示例
references/rustdoc-patterns.md
为发布准备文档
references/rustdoc-patterns.md

Source Notes

资料说明

Guidance is transformed and paraphrased from Herbert Wolverson, Advanced Hands-On Rust, especially Chapter 4 on documenting a library and Chapter 15 on sharing crates. Examples are original skeletons.
本指南改编自Herbert Wolverson所著的《Advanced Hands-On Rust》，尤其参考了第4章“库文档编写”和第15章“共享crates”的内容。示例为原创框架。