Rust 1.7.0 之 #![deny(missing_docs)]

现在我使用的Rust 环境是 V 1.7.0 ，因为在 Rust 的官方网站运行页面上的例子，有些地方执行后的结果和预期的不一样。

可能在 Rust 学习过程中，会遇到 Rust 语言不完善的地方。

这里根据实际的语句进行语法和语义的学习。

之前提到过 Rust 的注释，包括四种 :（详细内容见 /article/3713439.html）

1、//
2、/*   */
3、///
4、//!

又提到 Rust 的注解 attribute ，（详细内容见 /article/3731680.html）其中的 attribute包括了两类，

!#[attribute属性描述]

和

#[attribute属性描述]

带 !# 的是 for crate 的；

带 # 是 for item（item是一个新的术语，就是在 rust 中，除了crate之外，凡事在crate内的元素都称为item。根据类型不同，item又细分为 module、function、struct等等）

进入正题：

#![deny(missing_docs)]

这句前面是 !# ，因此是一个针对 crate 的注解。

deny 是lint 语法检查的注释（/article/3982874.html 第九类），含义是如果后面括号中的检查结果出现，将停止编译。

missing_docs 是 Rust 提供的 lint 语法检查名称，检查是否为指定的对象设置了文档注释。

$ cargo new attribute_test
$cd attribute_test
$cargo build

$ cargo build

Compiling attribute_test v0.1.0 (file:///Users/teamlet/develop/rust-projects/attribute_test)

可以正常编译。

$vi src/lib.rs

代码如下：

#[cfg(test)]
mod test {
#[test]
fn it_works() {
}
}

修改：前面加上 !#[deny(missing_docs)]

#![deny(missing_docs)]
#[cfg(test)]
mod test {
#[test]
fn it_works() {
}
}

保存并编译

cargo build
Compiling attribute_test v0.1.0 (file:///Users/teamlet/develop/rust-projects/attribute_test)
src/lib.rs:1:1: 8:1 error: missing documentation for crate
src/lib.rs:1 #![deny(missing_docs)]src/lib.rs:2
src/lib.rs:3 #[cfg(test)]
src/lib.rs:4 mod test {
src/lib.rs:5     #[test]
src/lib.rs:6     fn it_works() {
...
src/lib.rs:1:9: 1:21 note: lint level defined here
src/lib.rs:1 #![deny(missing_docs)]^~~~~~~~~~~~
error: aborting due to previous error
Could not compile `attribute_test`.

To learn more, run the command again with --verbose.

编译出现错误❌，错误提示：没有为crate写注释！

好，我们加上三种注释：1、// 2、/* */ 3、///

#![deny(missing_docs)]
// this is a line comments
/*
this is a block omments
*/

///  this is a documen line comments

#[cfg(test)]
mod test {
#[test]
fn it_works() {
}
}

错误依旧，还是不行！

好，那再加上第四个注释：//! 注意注释的位置

#![deny(missing_docs)]
// this is a line comments
/*
this is a block omments
*/

///  this is a documen line comments

//! comment
#[cfg(test)]
mod test {
#[test]
fn it_works() {
}
}

cargo build
Compiling attribute_test v0.1.0 (file:///Users/teamlet/develop/rust-projects/attribute_test)
src/lib.rs:10:1: 10:12 error: expected outer comment
src/lib.rs:10 //! comment
^~~~~~~~~~~
error: aborting due to previous error
Could not compile `attribute_test`.

To learn more, run the command again with --verbose.

错误提示变了，注释位置不对！

改正：

#![deny(missing_docs)]//! comments
// this is a line comments
/*
this is a block omments
*/

///  this is a documen line comments

#[cfg(test)]
mod test {
#[test]
fn it_works() {
}
}

编译通过 ✅！

换一个位置行不行？把 //! 注释放到 !# 之上

//! comments
#![deny(missing_docs)]
// this is a line comments
/*
this is a block omments
*/

///  this is a documen line comments

#[cfg(test)]
mod test {
#[test]
fn it_works() {
}
}

编译通过 ✅！

在 //! 之前，增加一些代码或者注释

#![deny(missing_docs)]
///
//! coments

// this is a line comments
/*
this is a block omments
*/

///  this is a documen line comments

#[cfg(test)]
mod test {
#[test]
fn it_works() {
}
}

这次在 //! 上面增加了一行注释 /// ，编译？

错误❌！

因此，

//!

是专为 crate 也就是整个文件设置注释的，

//!

注释可以写在

!#[deny(missing_docs)]

之前或者之后，但是不能写在任何 非 crate 内容之后。