src/doc/book/comments.md

   1 % Comments
   2
   3 Now that we have some functions, it’s a good idea to learn about comments.
   4 Comments are notes that you leave to other programmers to help explain things
   5 about your code. The compiler mostly ignores them.
   6
   7 Rust has two kinds of comments that you should care about: *line comments*
   8 and *doc comments*.
   9
  10 ```rust
  11 // Line comments are anything after ‘//’ and extend to the end of the line.
  12
  13 let x = 5; // This is also a line comment.
  14
  15 // If you have a long explanation for something, you can put line comments next
  16 // to each other. Put a space between the // and your comment so that it’s
  17 // more readable.
  18 ```
  19
  20 The other kind of comment is a doc comment. Doc comments use `///` instead of
  21 `//`, and support Markdown notation inside:
  22
  23 ```rust
  24 /// Adds one to the number given.
  25 ///
  26 /// # Examples
  27 ///
  28 /// ```
  29 /// let five = 5;
  30 ///
  31 /// assert_eq!(6, add_one(5));
  32 /// # fn add_one(x: i32) -> i32 {
  33 /// #     x + 1
  34 /// # }
  35 /// ```
  36 fn add_one(x: i32) -> i32 {
  37     x + 1
  38 }
  39 ```
  40
  41 There is another style of doc comment, `//!`, to comment containing items (e.g.
  42 crates, modules or functions), instead of the items following it. Commonly used
  43 inside crates root (lib.rs) or modules root (mod.rs):
  44
  45 ```
  46 //! # The Rust Standard Library
  47 //!
  48 //! The Rust Standard Library provides the essential runtime
  49 //! functionality for building portable Rust software.
  50 ```
  51
  52 When writing doc comments, providing some examples of usage is very, very
  53 helpful. You’ll notice we’ve used a new macro here: `assert_eq!`. This compares
  54 two values, and `panic!`s if they’re not equal to each other. It’s very helpful
  55 in documentation. There’s another macro, `assert!`, which `panic!`s if the
  56 value passed to it is `false`.
  57
  58 You can use the [`rustdoc`](documentation.html) tool to generate HTML documentation
  59 from these doc comments, and also to run the code examples as tests!