ドキュメンテーション - Rust By Example
Description: Rust by Example (RBE) is a collection of runnable examples that illustrate various Rust concepts and standard libraries.

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# ドキュメンテーション

Use `cargo doc` to build documentation in `target/doc`, `cargo doc --open` will automatically open it in your web browser.

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.

## ドキュメンテーションコメント

ドキュメンテーションコメントとは`rustdoc`を使用した際にドキュメントにコンパイルされるコメントのことです。`///`によって普通のコメントと区別され、ここではMarkdownを使用することができます。ドキュメンテーションコメントは大規模なプロジェクトの際に非常に有用です。

    #![crate_name = "doc"]

    /// あらゆる人物はここに代表されます。
    pub struct Person {
        /// ジュリエットがどんなに名前というものを嫌っていようと、
        /// 人物には名前が必要です。
        name: String,
    }

    impl Person {
        /// 与えられた名前を持つpersonを返します。
        ///
        /// # Examples
        ///
        /// ```
        /// // バッククォートによってRustのコードをコメント中に挟むこと
        /// // もできます。`rustdoc`に--testを渡せば、テストも行えます！
        /// // （訳注: pythonのdoctestと同じです。）
        /// use doc::Person;
        /// let person = Person::new("name");
        /// ```
        pub fn new(name: &str) -> Person {
            Person {
                name: name.to_string(),
            }
        }

        /// フレンドリーに挨拶しましょう！
        ///
        /// このメソッドを呼び出した`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
    pub 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.

### 参照

- The Rust Book: Making Useful Documentation Comments
- The rustdoc Book
- The Reference: Doc comments
- RFC 1574: API Documentation Conventions
- RFC 1946: Relative links to other items from doc comments (intra-rustdoc links)
- Is there any documentation style guide for comments? (reddit)