src/doc/rust-by-example/src/meta/doc.md

   1 # Documentation
   2
   3 Doc comments are very useful for big projects that require documentation. When
   4 running [Rustdoc][1], these are the comments that get compiled into
   5 documentation. They are denoted by a `///`, and support [Markdown][2].
   6
   7 ```rust,editable,ignore,mdbook-runnable
   8 #![crate_name = "doc"]
   9
  10 /// A human being is represented here
  11 pub struct Person {
  12     /// A person must have a name, no matter how much Juliet may hate it
  13     name: String,
  14 }
  15
  16 impl Person {
  17     /// Returns a person with the name given them
  18     ///
  19     /// # Arguments
  20     ///
  21     /// * `name` - A string slice that holds the name of the person
  22     ///
  23     /// # Example
  24     ///
  25     /// ```
  26     /// // You can have rust code between fences inside the comments
  27     /// // If you pass --test to Rustdoc, it will even test it for you!
  28     /// use doc::Person;
  29     /// let person = Person::new("name");
  30     /// ```
  31     pub fn new(name: &str) -> Person {
  32         Person {
  33             name: name.to_string(),
  34         }
  35     }
  36
  37     /// Gives a friendly hello!
  38     ///
  39     /// Says "Hello, [name]" to the `Person` it is called on.
  40     pub fn hello(& self) {
  41         println!("Hello, {}!", self.name);
  42     }
  43 }
  44
  45 fn main() {
  46     let john = Person::new("John");
  47
  48     john.hello();
  49 }
  50 ```
  51
  52 To run the tests, first build the code as a library, then tell rustdoc where
  53 to find the library so it can link it into each doctest program:
  54
  55 ```bash
  56 $ rustc doc.rs --crate-type lib
  57 $ rustdoc --test --extern doc="libdoc.rlib" doc.rs
  58 ```
  59
  60 (When you run `cargo test` on a library crate, Cargo will automatically
  61 generate and run the correct rustc and rustdoc commands.)
  62
  63 [1]: https://doc.rust-lang.org/book/documentation.html
  64 [2]: https://en.wikipedia.org/wiki/Markdown