src/doc/trpl/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 /// `hello` is a function that prints a greeting that is personalized based on
  25 /// the name given.
  26 ///
  27 /// # Arguments
  28 ///
  29 /// * `name` - The name of the person you'd like to greet.
  30 ///
  31 /// # Example
  32 ///
  33 /// ```rust
  34 /// let name = "Steve";
  35 /// hello(name); // prints "Hello, Steve!"
  36 /// ```
  37 fn hello(name: &str) {
  38     println!("Hello, {}!", name);
  39 }
  40 ```
  41
  42 When writing doc comments, adding sections for any arguments, return values,
  43 and providing some examples of usage is very, very helpful. Don't worry about
  44 the `&str`, we'll get to it soon.
  45
  46 You can use the [`rustdoc`](../rustdoc.html) tool to generate HTML documentation
  47 from these doc comments.