Rust 1.7.0 之 #![deny(missing_docs)]

现在我使用的Rust 环境是 V 1.7.0 ，因为在 Rust 的官方网站运行页面上的例子，有些地方执行后的结果和预期的不一样。
可能在 Rust 学习过程中，会遇到 Rust 语言不完善的地方。

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

之前提到过 Rust 的注释，包括四种 :（详细内容见 http://blog.csdn.net/teamlet/article/details/50855777）

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

又提到 Rust 的注解 attribute ，（详细内容见 http://blog.csdn.net/teamlet/article/details/50932225）其中的 attribute包括了两类，

!#[attribute属性描述]

和

#[attribute属性描述] 

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

进入正题：

#![deny(missing_docs)] 

这句前面是 !# ，因此是一个针对 crate 的注解。
deny 是lint 语法检查的注释（http://blog.csdn.net/teamlet/article/details/50936000 第九类），含义是如果后面括号中的检查结果出现，将停止编译。

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 cratesrc/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 heresrc/lib.rs:1 #![deny(missing_docs)]                 ^~~~~~~~~~~~error: aborting due to previous errorCould 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 commentsrc/lib.rs:10 //! comment              ^~~~~~~~~~~error: aborting due to previous errorCould 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 内容之后。