ドキュメントの書き方

このドキュメントでは、std/core の公開 API のドキュメントを書く方法を説明します。

まず、一般的な情報から始めましょう。

インラインコードブロックを使用する場合

型やコードに関連するものについて述べる場合は、必ず インラインコードブロックに入れるべきです。念のため、インラインコードブロックはバッククォート (`) で作成します。例:

This a `Vec` and it has a method `push` which you can call by doing `Vec::push`.

intra-doc リンクを使用する場合

intra-doc リンク（この機能の詳しい説明は こちらで確認できます）は、 型が言及される場合は可能な限り使用すべきです。

補足: 項目をドキュメント化している場合、その項目にリンクする必要はありません。 そのため、String::push_str メソッドのドキュメントを書く場合、 push_str メソッドや String 型にリンクする必要はありません。

コードブロック

rustdoc では、コードブロックはテストされます（デフォルトで Rust コードブロックとして扱われるためです）。 これにより、ドキュメントが最新の状態であるかを把握できます。そのため、 コードブロックでは可能な限り ignore の使用を避けてください！ Rust 以外の言語として扱いたい場合は、 コードブロックのタグで単にそれを設定してください。

```text
This is not rust code!
```

いくつかの特殊なケース:

• コード例を実行できない場合（たとえば I/O 項目をドキュメント化する場合）は、 no_run を使用します。
• 失敗することが期待される場合は、should_panic を使用します。
• コンパイルに失敗することが期待される場合（これはかなりまれなはずです！）は、compile_fail を使用します。

コードブロックについての詳細は こちらで確認できます。

モジュールのドキュメントの書き方

モジュールは「類似した」項目を含むことが想定されています。そのため、そのドキュメントは、 モジュールに含まれる項目が何を行うのかを理解するための概要と、最終的には 基礎 を提供することが想定されています。

良い例として、 f32 モジュール や fmt モジュール を参照できます。

関数/メソッドのドキュメントの書き方

ドキュメント化された各メソッド/関数の基本的な形式は、おおよそ次のようになるべきです。

[explanations]

[example(s)]

説明

explanations とは、そのメソッドが何をするのか、そして 各引数が何のためのものなのかを説明するテキストを意味します。例として次のメソッドを見てみましょう。

pub fn concat_str(&self, s: &str) -> String {
    if s.is_empty() {
        panic!("empty concat string");
    }
    format!("{}{}", self.string, s)
}

説明は次のようになるべきです。

Returns a new [`String`] which contains `&self` content with `s` added at the end.

Panic?

関数/メソッドが特定の状況で panic する可能性がある場合は、必ず 言及しなければなりません！ この説明には Panics というタイトルを前置する必要があります。

# Panics

`concat_str` panics if `s` is empty.

例

例については、関数/メソッドの使用方法を示す必要があります。 panic セクションと同様に、Example というタイトルを前置する必要があります（複数ある場合は複数形）。

最後に assert*! マクロを使用して、例が期待どおりに動作していることを確認するとよいです。 これにより、読者もその関数が何をしているのか（または何を返すのか）をより簡単に理解できます。

# Example

```
let s = MyType::new("hello ");
assert_eq!("hello Georges", s.concat_str("Georges").as_str());
```

その他の項目のドキュメントの書き方

例が（強く）推奨されるものの必須ではない点を除けば、メソッドや関数の場合とほとんど同じです。

良い例では、多くの場合、その項目の作成方法を示します。