Rust
ドキュメンテーション

前書き

構文

• ///外部の文書コメント（下記の項目に適用）

• //！内部文書のコメント（囲む項目に適用）

• cargo doc＃このライブラリクレートのドキュメントを生成します。

• cargo doc --open＃このライブラリの箱とオープンブラウザのドキュメントを生成します。

• cargo doc -p CRATE＃指定されたクレートの文書のみを生成します。

• cargo doc --no-deps＃このライブラリのドキュメントを生成します。依存関係はありません。

• cargo test＃ユニットテストとドキュメンテーションテストを実行します。

備考

ドキュメントの糸くず

可能なすべての項目が確実に文書化されるように、 missing_docsリンクを使用してコンパイラから警告/エラーを受け取ることができます。ライブラリ全体の警告を受け取るには、この属性をlib.rsファイルにlib.rsます。

#![warn(missing_docs)]

また、このlintを使って不足しているドキュメントのエラーを受け取ることもできます：

#![deny(missing_docs)]

デフォルトではmissing_docsが許可されていますが、この属性で明示的に許可することができます：

#![allow(missing_docs)]

これは、1つのモジュールを配置して1つのモジュールの不足しているドキュメントを許可するのに便利ですが、他のすべてのファイルでは拒否します。

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

Rustには、内部文書コメントと外部文書コメントの2種類の文書コメントがあります。それぞれの例を以下に示します。

内部文書コメント

mod foo {
    //! Inner documentation comments go *inside* an item (e.g. a module or a 
    //! struct). They use the comment syntax //! and must go at the top of the
    //! enclosing item. 
    struct Bar {
        pub baz: i64
        //! This is invalid. Inner comments must go at the top of the struct,
        //! and must not be placed after fields.
    }
}

外部のドキュメントのコメント

/// Outer documentation comments go *outside* the item that they refer to.
/// They use the syntax /// to distinguish them from inner comments.
pub enum Test {
    Success,
    Fail(Error)
}

コンベンション

/// In documentation comments, you may use **Markdown**.
/// This includes `backticks` for code, *italics* and **bold**.
/// You can add headers in your documentation, like this:
/// # Notes
/// `Foo` is unsuitable for snafucating. Use `Bar` instead.
struct Foo {
    ...
}

/// It is considered good practice to have examples in your documentation
/// under an "Examples" header, like this:
/// # Examples
/// Code can be added in "fences" of 3 backticks.
///
/// ```
/// let bar = Bar::new();
/// ```
///
/// Examples also function as tests to ensure the examples actually compile.
/// The compiler will automatically generate a main() function and run the
/// example code as a test when cargo test is run.
struct Bar {
    ...
}

ドキュメンテーションテスト

ドキュメンテーションコメントのコードは、 cargo testによって自動的に実行されcargo test 。これらは "ドキュメンテーションテスト"として知られており、あなたの例が確実に働き、あなたの木枠のユーザーを誤解させないようにします。

クレートルートから相対extern crate mycrate;をインポートすることができます（例の上に隠されたextern crate mycrate;があるかのように）

/// ```
/// use mycrate::foo::Bar;
/// ```

ドキュメントテストでコードが正しく実行されない場合は、次のようにno_run属性を使用できます。

/// ```no_run
/// use mycrate::NetworkClient;
/// NetworkClient::login("foo", "bar");
/// ```

次のように、コードがパニックに陥っていることを示すこともできます。

/// ```should_panic
/// unreachable!();
/// ```