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 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 内容之后。