ex3: 注释有四种写法

代码是写给人看的，只是顺便让机器执行而已。好的注释的作用不言而喻，会使得代码的可读性有极大的提高。在C的时代人们只有注释的概念，文档需要另外再写。而慢慢地人们发现，如果注释按照一定规范去做的话，文档是可以一键生成的。文档和注释都应该在代码中完成。所以Rust的注释虽然都不会被编译器所解析，但确实可以细分为文档型注释和普通注释的。

Python这点做得也比较差，不同人写有不同的风格，很难快速了解这个包有哪些组成部分，是如何工作的。所以每次去读文档非常地麻烦。而Rust在设计之处就对注释和文档进行了区分——简单来说，注释是给要了解这个包的源码的人看的，而文档是给只调用这个包，不关心内部实现的人看的。当然好的文档本身也可以很好地组织程序的架构。

Rust中的注释分为单行注释和块注释：

fn main() {
    // 行级注释
    // 与很多语言一样，都是两个"/"
    // 从这两个"/"到这一行结束（"\n")的任何内容都会被compiler忽略

    // 尝试将下面的hello world取消注释
    // println!("Hello, world!");

    // 在不同的编辑器里都有各自的快速注释的快捷键。如 mac 是command + /

    /* 
     * 另一种一般是大段注释时使用，块级注释
     * 以 "/*" 作为开始， 以"*/"作为结束
     * 实际上就是结束符号之后的内容又再次被compiler识别并处理
     * <---- 这样的"*"只是排版好看些，并没有任何作用
     */


    // 实际上块状注释还可以嵌在代码中间
    let x = 5 + /* 90 + */ 5;
    println!("Is `x` 10 or 100? x = {}", x);
}

而文档型注释则分为段前文档和段后文档，这里段的定义并不严格（可以是函数、结构体、结构体成员），这里用函数来举例：

/// 这是一个段前文档的示例
/// 段前段后并没有什么实际含义的区分
/// 一般情况下将段前文档写清楚就足够了
/// ## 这里支持markdown语言
pub fn test_function() {
    //! 这是一个段后文档
    //! 段后文档会直接拼在段前文档的后面
    2020;
}

/// 主函数入口
fn main() {
    println!("Hello, world!");
}

在代码中完成了文档型注释后，我们可以使用cargo来直接生成网页可浏览、可分享的文档。使用命令：

cargo doc --open

生成好的静态文件会在target/doc文件夹中，可以部署到服务器上。加上--open参数直接在默认浏览器中打开。可以看到上面文档型注释的内容已经被显示在页面中了。

养成良好的注释和文档书写习惯是一件非常有意义的事。

代码

补充说明