【Effective-Rustlings-jp】Day 17：パブリックインターフェースのドキュメントを書こう

# はじめに
こんにちは。細々とプログラミングをしている[sotanengel](https://x.com/sota_eng_prog)です。
この記事は以下の記事の連載です。

https://qiita.com/sotanengel/private/78103dcfe2fa34f8815e


<details>
<summary><strong>他の連載記事</strong> (<em>詳細</em>)</summary>

- [Day 1：型システムを使ってデータ構造を再現しよう](https://qiita.com/sotanengel/private/588a7f7cc03c36fc1adc)
- [Day 2：型システムを用いて共通の挙動を表現しよう](https://qiita.com/sotanengel/private/2a8fc62b6d9f8e916021)
- [Day 3：OptionとResultに対してはmatchを用いずに変換しよう](https://qiita.com/sotanengel/items/b54990dc82d877b9d70d)
- [Day 4：標準のErrorを使おう](https://qiita.com/sotanengel/private/79f683c3d75d09244567)
- [Day 5：型変換を理解しよう](https://qiita.com/sotanengel/private/8cc28c8b6108e5998e23)
- [Day 6：newtypeパターンを活用しよう](https://qiita.com/sotanengel/private/38814f8b5a88aad9eccc)
- [Day 7：複雑な型にはビルダを使おう](https://qiita.com/sotanengel/private/80bc555e95ed56b72f14)
- [Day 8：明示的なループの代わりにイテレータ変換を使用することを検討しよう](https://qiita.com/sotanengel/private/f7f4fc03f0b2dc445bf2)
- [Day 9：標準トレイトに習熟しよう](https://qiita.com/sotanengel/private/24a8ad443fc23e779ccd)
- [Day 10：RIIパターンにはDropトレイトを実装しよう](https://qiita.com/sotanengel/private/a3d1b04f98ea80b8989d)
- [Day 11：ジェネリクスとトレイトオブジェクトのトレードオフを理解しよう](https://qiita.com/sotanengel/private/8e2e88d5619b434c3ada)
- [Day 12：デフォルト実装を用いて、実装しなければならないトレイトメソッドを最小限にしよう](https://qiita.com/sotanengel/private/16b02d32732727eaf66f)
- [Day 13：Don't panic](https://qiita.com/sotanengel/private/aa833ce99c8e8b8eecf2)
- [Day 14：リフレクションを避けよう](https://qiita.com/sotanengel/private/6108b22f6644d4fde997)
- [Day 15：可視範囲を最小化しよう](https://qiita.com/sotanengel/private/4075925e05de50dfac96)
- [Day 16：ワイルドカードインポートを避けよう](https://qiita.com/sotanengel/private/555314f77c8318bb1c45)
- [Day 17：パブリックインターフェースのドキュメントを書こう](https://qiita.com/sotanengel/private/b4e8a11522b253ebb62e)
- [Day 18：分別を持ってマクロを使おう](https://qiita.com/sotanengel/private/a33b5ab66a82a26b4adc)
- [Day 19：Clippyに耳を傾けよう](https://qiita.com/sotanengel/private/b4c161bb87fc9e7e813e)
- [Day 20：ユニットテスト以上のものを書こう](https://qiita.com/sotanengel/private/58fcafaee5418b2b2b16)

</details>

また本記事は[Effective Rust(David Drysdale (著), 中田 秀基 (翻訳))](https://www.oreilly.com/library/view/effective-rust/9781098151393/)を参考に作成されております。とてもいい書籍ですので興味を持った方は、ぜひ読んでみてください！
<div style="text-align: center;">
  <figure>
    <a href="https://www.amazon.co.jp/Effective-Rust-%E2%80%95Rust%E3%82%B3%E3%83%BC%E3%83%89%E3%82%92%E6%94%B9%E5%96%84%E3%81%97%E3%80%81%E3%82%A8%E3%82%B3%E3%82%B7%E3%82%B9%E3%83%86%E3%83%A0%E3%82%92%E6%9C%80%E5%A4%A7%E9%99%90%E3%81%AB%E6%B4%BB%E7%94%A8%E3%81%99%E3%82%8B%E3%81%9F%E3%82%81%E3%81%AE35%E9%A0%85%E7%9B%AE-David-Drysdale/dp/4814400942"  target="_blank">
      <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1758960/cb1245be-02d6-0c74-8b79-e46288f2ea73.png" alt="商品画像" width="50%">
    </a>
  </figure>
</div>

# 今日の内容
## 概要
Rustは`cargo doc`を実行することで自動的にドキュメントを作成することができます。
どのように書くのか確かめてみましょう。

## ドキュメントの書き方を確かめてみよう
### 問([リンク](https://github.com/sotanengel/effective-rustlings-jp/blob/20250101/exercises/27_tooling_Document_public_interfaces/1_write_doc.rs))
`TODO`と書かれている部分を修正してみましょう。

<details>
<summary><strong>コード</strong> (<em>詳細</em>)</summary>

```rust
/// # 概要
///
/// 文字列を整数にパースし、指定したメッセージとともに出力する関数です。
/// TODO: クロスリファレンス記法で書くことでハイパーリンクを付与しましょう。
/// このサンプルコードでは、パースに失敗した場合に `panic!` マクロで
/// 強制終了する例を示しています。
///
/// # サンプルコード
/// TODO: コードを書く部分には「```」で囲んで記載してみましょう。
///
/// // この関数は例示のために作成したモジュールに含まれていますが、
/// // 実際には適宜修正してご利用ください。
/// //
/// // example モジュールを使うことを想定したサンプル
/// use example::parse_and_print;
///
/// // 整数文字列をパースし、出力する
/// let result = parse_and_print("42", "解析成功");
/// // 正しくパースできた場合は Ok(42) が返る
/// assert_eq!(result, Ok(42));
///
/// // パースに失敗した場合は panic! となります
/// // let result_fail = parse_and_print("abc", "解析失敗"); // panic!
///
///
/// # Panics
/// TODO: パニック条件を記載してみましょう。
/// - 入力文字列を [`i32::parse()`] でパースできない場合、
///   [`panic!`] で強制終了します。  
/// - [`panic!`](https://doc.rust-lang.org/std/macro.panic.html) マクロは
///   リカバリ不能なエラーを表すために使われるもので、アプリケーション全体を終了させます。
///
/// # Safety
///
/// この関数では、内部で一部 [`unsafe`](https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html) ブロックを使用しています。
/// Rust では [`unsafe`] コードはメモリ安全性をコンパイラに保証させないため、
/// 十分に注意して取り扱う必要があります。
/// 以下のように一時的にポインタを変換する処理を含んでいますが、
/// 安全性については利用者自身が確認する責任を負います。
///
/// ```
/// // unsafeブロックの例
/// unsafe {
///     let num_ref: *const i32 = &10;
///     let num_mut_ref = num_ref as *mut i32;
///     // ポインタ操作等、通常の安全なRustでは禁止される操作が可能
/// }
/// ```
///
/// # パラメータ
///
/// * `input` - 整数へ変換したい文字列
/// * `message` - ログ出力や表示に使用するメッセージ
///
/// # 戻り値
///
/// * `Ok(i32)` - `input` のパースに成功した場合  
/// * `Err(std::num::ParseIntError)` - `input` のパースに失敗した場合
///
/// # 関連項目
///
/// - [`String`](https://doc.rust-lang.org/std/string/struct.String.html)
/// - [`Result`](https://doc.rust-lang.org/std/result/enum.Result.html)
/// - [`Option`](https://doc.rust-lang.org/std/option/enum.Option.html)
/// - [`panic!`](https://doc.rust-lang.org/std/macro.panic.html)
/// - [`i32::parse()`](https://doc.rust-lang.org/std/primitive.i32.html#method.parse)
///
/// # 実装例
///
pub fn parse_and_print(input: &str, message: &str) -> Result<i32, std::num::ParseIntError> {
    // 文字列を整数にパースできるかチェック
    // TODO: 文字列を整数にパースする処理を書いてください。
    //       成功した場合 => i32の数を返却する,
    //       失敗した場合 => panicして「Failed to parse the input string: エラー文」
    let value: i32 = 
    };

    // unsafeブロックの例示
    #[allow(unused_unsafe)]
    unsafe {
        let ptr: *const i32 = &value;
        let _mut_ptr = ptr as *mut i32;
        // ここで任意の不正な操作が可能なため、十分に注意が必要
    }

    // パースに成功したらメッセージと共に表示
    println!("{}: {}", message, value);

    // 結果を返す
    Ok(value)
}

use std::env;

fn main() {
    // コマンドライン引数をベクタに収集
    let args: Vec<String> = env::args().collect();

    // 第1引数があれば使用し、なければ "42" をデフォルト値とする
    let input_str = args.get(1).map(|s| s.as_str()).unwrap_or("42");
    // 第2引数があれば使用し、なければ "解析結果" をデフォルト値とする
    let message = args.get(2).map(|s| s.as_str()).unwrap_or("解析結果");

    // parse_and_print を呼び出し、その戻り値を表示
    match parse_and_print(input_str, message) {
        Ok(n) => println!("parse_and_print の戻り値: {}", n),
        Err(e) => println!("エラーが発生しました: {}", e),
    };
}
```

</details>

### 解答([リンク](https://github.com/sotanengel/effective-rustlings-jp/blob/20250101/solutions/27_tooling_Document_public_interfaces/1_write_doc.rs))
コード参照。

<details>
<summary><strong>コード</strong> (<em>詳細</em>)</summary>

```rust
/// # 概要
///
/// 文字列を整数にパースし、指定したメッセージとともに出力する関数です。
/// このサンプルコードでは、パースに失敗した場合に [`panic!`] マクロで
/// 強制終了する例を示しています。
///
/// # サンプルコード
///
/// ```
/// // この関数は例示のために作成したモジュールに含まれていますが、
/// // 実際には適宜修正してご利用ください。
/// //
/// // example モジュールを使うことを想定したサンプル
/// use example::parse_and_print;
///
/// // 整数文字列をパースし、出力する
/// let result = parse_and_print("42", "解析成功");
/// // 正しくパースできた場合は Ok(42) が返る
/// assert_eq!(result, Ok(42));
///
/// // パースに失敗した場合は panic! となります
/// // let result_fail = parse_and_print("abc", "解析失敗"); // panic!
/// ```
///
/// # Panics
/// TODO: パニック条件を記載してみましょう。
/// - 入力文字列を [`i32::parse()`] でパースできない場合、
///   [`panic!`] で強制終了します。  
/// - [`panic!`](https://doc.rust-lang.org/std/macro.panic.html) マクロは
///   リカバリ不能なエラーを表すために使われるもので、アプリケーション全体を終了させます。
///
/// # Safety
///
/// この関数では、内部で一部 [`unsafe`](https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html) ブロックを使用しています。
/// Rust では [`unsafe`] コードはメモリ安全性をコンパイラに保証させないため、
/// 十分に注意して取り扱う必要があります。
/// 以下のように一時的にポインタを変換する処理を含んでいますが、
/// 安全性については利用者自身が確認する責任を負います。
///
/// ```
/// // unsafeブロックの例
/// unsafe {
///     let num_ref: *const i32 = &10;
///     let num_mut_ref = num_ref as *mut i32;
///     // ポインタ操作等、通常の安全なRustでは禁止される操作が可能
/// }
/// ```
///
/// # パラメータ
///
/// * `input` - 整数へ変換したい文字列
/// * `message` - ログ出力や表示に使用するメッセージ
///
/// # 戻り値
///
/// * `Ok(i32)` - `input` のパースに成功した場合  
/// * `Err(std::num::ParseIntError)` - `input` のパースに失敗した場合
///
/// # 関連項目
///
/// - [`String`](https://doc.rust-lang.org/std/string/struct.String.html)
/// - [`Result`](https://doc.rust-lang.org/std/result/enum.Result.html)
/// - [`Option`](https://doc.rust-lang.org/std/option/enum.Option.html)
/// - [`panic!`](https://doc.rust-lang.org/std/macro.panic.html)
/// - [`i32::parse()`](https://doc.rust-lang.org/std/primitive.i32.html#method.parse)
///
/// # 実装例
///
pub fn parse_and_print(input: &str, message: &str) -> Result<i32, std::num::ParseIntError> {
    // 文字列を整数にパースできるかチェック
    let value: i32 = match input.parse::<i32>() {
        Ok(n) => n,
        Err(e) => {
            // パースに失敗したら panic! する
            panic!("Failed to parse the input string: {:?}", e);
        }
    };

    // unsafeブロックの例示
    #[allow(unused_unsafe)]
    unsafe {
        let ptr: *const i32 = &value;
        let _mut_ptr = ptr as *mut i32;
        // ここで任意の不正な操作が可能なため、十分に注意が必要
    }

    // パースに成功したらメッセージと共に表示
    println!("{}: {}", message, value);

    // 結果を返す
    Ok(value)
}

use std::env;

fn main() {
    // コマンドライン引数をベクタに収集
    let args: Vec<String> = env::args().collect();

    // 第1引数があれば使用し、なければ "42" をデフォルト値とする
    let input_str = args.get(1).map(|s| s.as_str()).unwrap_or("42");
    // 第2引数があれば使用し、なければ "解析結果" をデフォルト値とする
    let message = args.get(2).map(|s| s.as_str()).unwrap_or("解析結果");

    // parse_and_print を呼び出し、その戻り値を表示
    match parse_and_print(input_str, message) {
        Ok(n) => println!("parse_and_print の戻り値: {}", n),
        Err(e) => println!("エラーが発生しました: {}", e),
    };
}
```

</details>

# さいごに

もしも本リポジトリで不備などあれば、リポジトリのissueやPRなどでご指摘いただければと思います。

https://github.com/sotanengel/effective-rustlings-jp/issues