如何编写 crate-wide 文档？

Question

为了确保我的 crate 的所有 public 工件都被记录（如果是最低限度的开始），我在我的 lib.rs 中指定了 #![deny(missing_docs)]。这事与愿违。

我希望在顶部写一个文档注释，然后再写代码：

/// Hello world example for Rust.

#![deny(missing_docs)]

fn main() {
    println!("Hello world!");
}

这失败了：

error: an inner attribute is not permitted following an outer doc comment
 --> src/main.rs:3:3
  |
3 | #![deny(missing_docs)]
  |   ^
  |
  = note: inner attributes, like `#![no_std]`, annotate the item enclosing them, and are usually found at the beginning of source files. Outer attributes, like `#[test]`, annotate the item following them.

正在反转顺序，属性在前，评论在后：

#![deny(missing_docs)]

/// Hello world example for Rust.

fn main() {
    println!("Hello world!");
}

同样失败：

error: missing documentation for crate
 --> src/main.rs:1:1
  |
1 | / #![deny(missing_docs)]
2 | |
3 | | /// Hello world example for Rust.
4 | |
5 | | fn main() {
6 | |     println!("Hello world!");
7 | | }
  | |_^
  |
note: lint level defined here
 --> src/main.rs:1:9
  |
1 | #![deny(missing_docs)]
  |         ^^^^^^^^^^^^

我找不到如何真正为 crate 本身编写文档。我应该如何编写 crate 的文档以满足 #![deny(missing_docs)]?

Answer 1

我在 book's Publishing a Crate to Crates.io section 中找到了隐藏的金块。

常规文档注释（从 /// 开始）记录 下一个 项目，但是箱子不是下一个。

解决方案是改用另一种注释，这次从 //! 开始，它记录 封闭的 项。

突然间它起作用了：

#![deny(missing_docs)]

//! Hello world example for Rust.

fn main() {
    println!("Hello world!");
}

如何编写 crate-wide 文档？

How can I write crate-wide documentation?

documentation

rust