• 注释

    注释

    comments.md


    commit ccb1d87d6faa9ff528d22b96595a0e2cbb16c0f2

    现在我们写了一些函数，是时候学习一下注释了。注释是你帮助其他程序员理解你的代码的备注。编译器基本上会忽略它们。

    Rust 有两种需要你了解的注释格式：行注释（line comments）和文档注释（doc comments）。

    1. // Line comments are anything after ‘//’ and extend to the end of the line.
    3. let x = 5; // This is also a line comment.
    5. // If you have a long explanation for something, you can put line comments next
    6. // to each other. Put a space between the // and your comment so that it’s
    7. // more readable.

    另一种注释是文档注释。文档注释使用///而不是//，并且内建 Markdown 标记支持：

    1. /// Adds one to the number given.
    2. ///
    3. /// # Examples
    4. ///
    5. /// ```
    6. /// let five = 5;
    7. ///
    8. /// assert_eq!(6, add_one(5));
    9. /// # fn add_one(x: i32) -> i32 {
    10. /// #     x + 1
    11. /// # }
    12. /// ```
    13. fn add_one(x: i32) -> i32 {
    14.     x + 1
    15. }

    有另外一种风格的文档注释，//!，用来注释包含它的项（也就是说，crate，模块或者函数），而不是位于它之后的项。它经常用在 crate 根文件（lib.rs）或者模块根文件（mod.rs）：

    1. //! # The Rust Standard Library
    2. //!
    3. //! The Rust Standard Library provides the essential runtime
    4. //! functionality for building portable Rust software.

    当书写文档注释时，加上参数和返回值部分并提供一些用例将是非常，非常有帮助的。你会注意到我们在这里用了一个新的宏：assert_eq!。它比较两个值，并当它们不相等时panic!。这在文档中是非常有帮助的。还有一个宏，assert!，它在传递给它的值是false的时候panic!。

    你可以使用rustdoc工具来将文档注释生成为 HTML 文档，也可以将代码示例作为测试运行！