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.
#![crate_name = "doc"] /// A human being is represented here pub struct Person { /// A person must have a name, no matter how much Juliet may hate it name: String, } impl Person { /// Returns a person with the name given them /// /// # Arguments /// /// * `name` - A string slice that holds the name of the person /// /// # Example /// /// ``` /// // You can have rust code between fences inside the comments /// // If you pass --test to Rustdoc, it will even test it for you! /// use doc::Person; /// let person = Person::new("name"); /// ``` pub fn new(name: &str) -> Person { Person { name: name.to_string(), } } /// Gives a friendly hello! /// /// Says "Hello, [name]" to the `Person` it is called on. pub fn hello(& self) { println!("Hello, {}!", self.name); } } fn main() { let john = Person::new("John"); john.hello(); }
To run the tests, first build the code as a library, then tell rustdoc where to find the library so it can link it into each doctest program:
$ rustc doc.rs --crate-type lib
$ 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.)