documentation - 如何编写 crate-wide 文档？

Question

为了确保我的箱子的所有公共(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 中找到了隐藏的金 block .

常规文档注释(以 /// 开头)记录下一个 项目，但是箱子不是下一个。

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

突然间它起作用了:

#![deny(missing_docs)]

//! Hello world example for Rust.

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