Documentation

Doc comments are very useful for big projects that require documentation. When
running Rustdoc, these are the comments that get compiled into
documentation. They are denoted by a ///, and support Markdown.

  1. #![crate_name = "doc"]
  3. /// A human being is represented here
  4. pub struct Person {
  5.     /// A person must have a name, no matter how much Juliet may hate it
  6.     name: String,
  7. }
  9. impl Person {
  10.     /// Returns a person with the name given them
  11.     ///
  12.     /// # Arguments
  13.     ///
  14.     /// * `name` - A string slice that holds the name of the person
  15.     ///
  16.     /// # Example
  17.     ///
  18.     ///
  1. /// // You can have rust code between fences inside the comments
  2. /// // If you pass --test to Rustdoc, it will even test it for you!
  3. /// use doc::Person;
  4. /// let person = Person::new("name");
  5. /// ```
  6. pub fn new(name: &str) -> Person {
  7.     Person {
  8.         name: name.to_string(),
  9.     }
  10. }
  12. /// Gives a friendly hello!
  13. ///
  14. /// Says "Hello, [name]" to the `Person` it is called on.
  15. pub fn hello(& self) {
  16.     println!("Hello, {}!", self.name);
  17. }

}

fn main() {
let john = Person::new(“John”);

  1. john.hello();

}

  2. To run the tests, first build the code as a library, then tell rustdoc where
  3. to find the library so it can link it into each doctest program:
  5. ```bash
  6. $ rustc doc.rs --crate-type lib
  7. $ rustdoc --test --extern doc="libdoc.rlib" doc.rs

(When you run cargo test on a library crate, Cargo will automatically
generate and run the correct rustc and rustdoc commands.)