ドキュメンテーション

/// 2 つの数値を加算する．
///
/// # Examples
///
/// ```
/// let result = my_crate::add(1, 2);
/// assert_eq!(result, 3);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

//! # My Crate
//!
//! `my_crate` は数学的な操作を提供するライブラリです．
//! このドキュメントはクレートレベルの説明として機能します．

/// TCP ストリームからデータを読み取る．
///
/// # Arguments
///
/// * `buf` - データを格納するバッファ
///
/// # Returns
///
/// 読み取ったバイト数を返す．
///
/// # Errors
///
/// ソケットが閉じている場合，`io::Error` を返す．
///
/// # Panics
///
/// `buf` の長さが 0 の場合，パニックする．
///
/// # Safety
///
/// (unsafe 関数の場合) この関数を安全に呼ぶための前提条件を記述する．
///
/// # Examples
///
/// ```no_run
/// use std::net::TcpStream;
/// use std::io::Read;
///
/// let mut stream = TcpStream::connect("127.0.0.1:8080").unwrap();
/// let mut buf = [0u8; 1024];
/// let n = stream.read(&mut buf).unwrap();
/// ```
pub fn read(buf: &mut [u8]) -> io::Result<usize> {
    // ...
}

/// 数値が偶数かどうかを判定する．
///
/// # Examples
///
/// ```
/// assert!(my_crate::is_even(4));
/// assert!(!my_crate::is_even(3));
/// ```
pub fn is_even(n: i32) -> bool {
    n % 2 == 0
}

cargo test

   Doc-tests my_crate

running 1 test
test src/lib.rs - is_even (line 5) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored

/// # Examples
///
/// コンパイルが通ることだけを確認（実行はしない）:
/// ```no_run
/// let mut file = std::fs::File::create("output.txt").unwrap();
/// ```
///
/// コンパイルエラーになることを期待:
/// ```compile_fail
/// let x: i32 = "hello";
/// ```
///
/// テストとして実行しない（擬似コードや説明目的）:
/// ```ignore
/// // この例は外部サービスが必要
/// let response = fetch_from_api().await;
/// ```
///
/// 隠れた行（ドキュメント表示では非表示，テストでは実行される）:
/// ```
/// # use std::collections::HashMap;
/// # fn main() {
/// let mut map = HashMap::new();
/// map.insert("key", "value");
/// assert_eq!(map["key"], "value");
/// # }
/// ```

cargo doc --open

/// [`Vec`] と同様のインターフェースを持つ．
///
/// 詳細は [`Self::push`] を参照．
///
/// [`HashMap`](std::collections::HashMap) も参考にするとよい．
pub struct MyCollection {
    // ...
}

// clippy::missing_docs_in_private_items (pedantic)
// pub なアイテムにドキュメントコメントがない場合に警告

// clippy::missing_errors_doc
// Result を返す pub 関数に # Errors セクションがない場合に警告

// clippy::missing_panics_doc
// パニックしうる pub 関数に # Panics セクションがない場合に警告

/// これはドキュメントコメント
pub fn foo() {}

// ↑ これは以下と同等
#[doc = "これはドキュメントコメント"]
pub fn foo() {}

macro_rules! make_documented_fn {
    ($name:ident, $doc:expr) => {
        #[doc = $doc]
        pub fn $name() {}
    };
}

make_documented_fn!(hello, "挨拶を行う関数．");