如何编写crate-wide文档？

Question

为了确保记录我的箱子的所有公共工件(如果最低限度开始),我#![deny(missing_docs)]在我的指定lib.rs,但它适得其反.

我希望编写这样的代码,即顶部的文档注释和后面的代码:

/// 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)]
  |         ^^^^^^^^^^^^

在本书的文档部分中,我找不到如何为箱子本身编写文档.

那么,我应该如何写箱子文件以满足#![deny(missing_docs)]？

Answer 1

我实际上在本书的文档部分找到了隐藏的金块.

定期文档注释(从开始///)记录下一个项目,但是下一个项目是没人的.

因此,解决方案是切换到使用另一种注释,这次开始于//!,记录封闭项.

突然它起作用了:

#![deny(missing_docs)]

//! Hello world example for Rust.

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