ドキュメンテーション

Use cargo doc to build documentation in target/doc.

Use cargo test to run all tests (including documentation tests), and cargo test --doc to only run documentation tests.

These commands will appropriately invoke rustdoc (and rustc) as required.

Doc comments

ドキュメンテーションコメントとはrustdocを使用した際にドキュメントにコンパイルされるコメントのことです。///によって普通のコメントと区別され、ここでは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
    /// 与えられた名前を持つpersonを返します。
    ///
    /// # Arguments
    ///
    /// * `name` - A string slice that holds the name of the person
    /// * `name` - `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!
    /// // バッククォートによってRustのコードをコメント中に挟むこと
    /// // もできます。`rustdoc`に--testを渡せば、テストも行えます！
    /// // （訳注: pythonのdoctestと同じです。）
    /// 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](Person::name)" to the `Person` it is called on.
    /// このメソッドを呼び出した`Person`に対して"Hello, [name](Person::name)"
    /// と話しかけます。
    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

Doc attributes

Below are a few examples of the most common #[doc] attributes used with rustdoc.

inline

Used to inline docs, instead of linking out to separate page.

#[doc(inline)]
pub use bar::Bar;

/// bar docs
mod bar {
    /// the docs for Bar
    pub struct Bar;
}

no_inline

Used to prevent linking out to separate page or anywhere.

// Example from libcore/prelude
#[doc(no_inline)]
pub use crate::mem::drop;

hidden

Using this tells rustdoc not to include this in documentation:

// Example from the futures-rs library
#[doc(hidden)]
pub use self::async_await::*;

For documentation, rustdoc is widely used by the community. It's what is used to generate the std library docs.

参照