Documentation

Recipe	Crates	Categories
Document Your Code
Create Module- or Crate-level Documentation
Add Documentation to Function Arguments in Rust

Document Your Code

• Add documentation comments to your code.

/// This is a doc comment.
/// Note the three slashes.
/// The first line is equivalent to the following:
#[doc = "This is a doc comment."]
fn documented_function() {
    println!("Function with doc comment.");
}

// Alternatively, you may use an external file.
// This is useful for including large amounts of documentation.
#[doc = include_str!("../../../../README.md")]
fn function_including_external_file_as_documentation() {}

fn main() {
    documented_function();
    function_including_external_file_as_documentation();
}

rustdoc⮳ uses the CommonMark Markdown specification.

#![allow(dead_code)]

/// Returns a `Person` struct with the given name.
///
/// # Arguments
///
/// * `name` - A string slice that holds the name of the person.
///
/// # Examples
///
/// ```
/// // You can have Rust code between fences inside the comments.
/// // If you pass `--test` to `rustdoc`, it will even test it for you!
/// let person = Person::new("name");
/// ```
fn new(name: &str) -> Person {
    Person {
        name: name.to_string(),
    }
}

#[derive(Debug)]
struct Person {
    name: String,
}

fn main() {
    let john = new("John");
    println!("{:?}", john);
}

Any item annotated with #[doc(hidden)] will not appear in the documentation.

Run rustdoc src/lib.rs --crate-name <name> or cargo doc --open to create a new directory, doc (or target/doc when using cargo), with a website inside.

Create Module- or Crate-level Documentation

Use //! at the top of the file (instead of ///) for module-level documentation.

The first lines within lib.rs will compose the crate-level documentation front-page.

//! Fast and easy queue abstraction.
//!
//! Provides an abstraction over a queue. When the abstraction is used
//! there are these advantages:
//! - Fast
//! - `[Easy]`
//!
//! [Easy]: http://thatwaseasy.example.com

fn main() {
    println!(
        "//! ... are `inner` comments that apply to the containing module (or crate)."
    );
}

To add a "run" button on your documentation (allowing its execution in the rust playground), use the following attribute:

#![doc(html_playground_url = "https://playground.example.com/")]

/// This is a simple example to demonstrate the use of the
/// `html_playground_url` attribute.
///
/// You can click on the "Run" button in the documentation to execute this code
/// in the playground.
fn main() {
    println!(
        "Note the above doc attribute is an _inner_ attribute that starts with #!"
    );
    println!("It should be place at the top of your crate.")
}

Add Documentation to Function Arguments in Rust

roxygen⮳ helps seamlessly document function parameters with rustdoc⮳.

References

• The rustdoc book⮳.
• docs.rs⮳: open-source documentation host for Rust crates.