課題21: ライブラリドキュメント作成

マンダトリー要件

問題1：ドキュメントの理解（15点）

以下の質問に答えなさい。

• コメントの種類（5点）

• 標準セクション（5点）

• ドキュメントテスト（5点）

問題2：データ構造ライブラリのドキュメント（35点）

以下のデータ構造ライブラリに完全なドキュメントを追加しなさい。

// src/lib.rs

pub mod stack;
pub mod queue;
pub mod linked_list;

2.1 スタック（12点）

// src/stack.rs

pub struct Stack<T> {
    items: Vec<T>,
}

impl<T> Stack<T> {
    pub fn new() -> Self {
        // ドキュメントを追加
        Stack { items: Vec::new() }
    }

    pub fn push(&mut self, item: T) {
        // ドキュメントを追加
        self.items.push(item);
    }

    pub fn pop(&mut self) -> Option<T> {
        // ドキュメントを追加
        self.items.pop()
    }

    pub fn peek(&self) -> Option<&T> {
        // ドキュメントを追加
        self.items.last()
    }

    pub fn is_empty(&self) -> bool {
        // ドキュメントを追加
        self.items.is_empty()
    }

    pub fn len(&self) -> usize {
        // ドキュメントを追加
        self.items.len()
    }
}

要件：

• すべての公開関数にドキュメント
• 少なくとも2つの# Examples
• ジェネリック型パラメータの説明
• モジュールレベルのドキュメント

2.2 キュー（12点）

// src/queue.rs

use std::collections::VecDeque;

pub struct Queue<T> {
    items: VecDeque<T>,
}

impl<T> Queue<T> {
    pub fn new() -> Self {
        // ドキュメントを追加
    }

    pub fn enqueue(&mut self, item: T) {
        // ドキュメントを追加
    }

    pub fn dequeue(&mut self) -> Option<T> {
        // ドキュメントを追加
    }

    pub fn front(&self) -> Option<&T> {
        // ドキュメントを追加
    }
}

要件：

• FIFO動作の説明
• 使用例
• 時間計算量の説明

2.3 クレートドキュメント（11点）

// src/lib.rs
//! ドキュメントを追加

要件：

• クレートの説明
• Quick Startガイド
• インストール方法
• モジュールへのリンク

問題3：APIドキュメント（30点）

以下のAPIに完全なドキュメントを追加しなさい。

use std::fs::File;
use std::io::{self, Read};

/// ドキュメントを追加
pub struct Config {
    pub host: String,
    pub port: u16,
    pub timeout: u64,
}

impl Config {
    /// ドキュメントを追加
    pub fn new(host: String, port: u16) -> Self {
        // 実装
    }

    /// ドキュメントを追加
    pub fn from_file(path: &str) -> io::Result<Self> {
        // 実装
    }

    /// ドキュメントを追加
    pub fn validate(&self) -> Result<(), String> {
        // 実装
    }
}

/// ドキュメントを追加
pub trait Connector {
    /// ドキュメントを追加
    fn connect(&mut self, config: &Config) -> io::Result<()>;

    /// ドキュメントを追加
    fn disconnect(&mut self) -> io::Result<()>;

    /// ドキュメントを追加
    fn is_connected(&self) -> bool;
}

要件：

• すべての公開アイテムにドキュメント
• # Examplesセクション（各関数に最低1つ）
• # Errorsセクション（該当関数）
• トレイトの実装例
• リンク（型、関数へのリンク）

---

ボーナス課題

ボーナス1：高度なドキュメント機能（10点）

以下の高度なドキュメント機能を使用しなさい。

• カスタムセクション

   /// # Time Complexity
   ///
   /// O(1) for insertion, O(n) for search
   ///
   /// # Space Complexity
   ///
   /// O(n) where n is the number of elements
   

• バージョン情報

   /// # Version
   ///
   /// Added in: 1.0.0
   /// Deprecated in: 2.0.0 (use [`new_api`] instead)
   

• インラインリンク

   /// Returns a [`Result`] containing a [`Config`].
   ///
   /// See also: [`validate`](Config::validate)
   

ボーナス2：ドキュメントテストの完全カバレッジ（10点）

すべての公開関数に対して、以下を含むドキュメントテストを作成しなさい：

• 正常系のテスト
• エラーケースのテスト（should_panic）
• エッジケースのテスト

/// # Examples
///
/// 正常な使用：
/// 

///
/// ゼロ除算エラー：
/// 

///
/// 浮動小数点の精度：
/// 

pub fn divide(a: f64, b: f64) -> Result<f64, String> {
    if b == 0.0 {
        Err("ゼロ除算エラー".to_string())
    } else {
        Ok(a / b)
    }
}

ボーナス3：ドキュメント公開（10点）

ドキュメントを公開し、以下を提出しなさい：

• GitHub Pagesでの公開

• docs.rsでの公開

• README.md

GitHub Actions例：

name: Deploy Docs

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build docs
        run: cargo doc --no-deps
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./target/doc

ボーナス4：ドキュメント品質分析（10点）

ドキュメントの品質を分析し、レポートを作成しなさい。

分析項目：

• カバレッジ

• 可読性

• 改善提案

ツール：

# 警告を表示
cargo rustdoc -- -W missing-docs

# すべての警告をエラーに
RUSTDOCFLAGS="-D warnings" cargo doc

---

評価基準

マンダトリー部分（80点）

ボーナス部分（20点）

注: ボーナスは最大20点まで加算されます。

---

提出方法

ファイル構成

rust-foundations-21/
├── Cargo.toml
├── README.md
├── src/
│   ├── lib.rs
│   ├── stack.rs
│   ├── queue.rs
│   └── linked_list.rs
├── answers.md              # 問題1の回答
├── .github/
│   └── workflows/
│       └── docs.yml        # ボーナス3用
└── quality_report.md       # ボーナス4用

ドキュメント生成

# ローカルでドキュメント生成
cargo doc --open

# ドキュメントテスト実行
cargo test --doc

# 警告チェック
RUSTDOCFLAGS="-D warnings" cargo doc

---

ヒント

問題2のヒント

モジュールドキュメントの例：

//! スタックデータ構造の実装。
//!
//! このモジュールはLIFO（Last In First Out）原則に基づく
//! スタックデータ構造を提供します。
//!
//! # Examples
//!
//! 

問題3のヒント

リンクの作成：

/// [`Config`]を使って接続を確立します。
///
/// 詳細は[`Connector`]トレイトを参照してください。
///
/// [`Config::validate`]を先に呼び出すことを推奨します。

ボーナス2のヒント

隠しコードの活用：

/// # Examples
///
/// 

---

学習の確認

この課題を通じて、以下を理解できたか確認してください：

• [ ] rustdocの基本的な使い方
• [ ] マークダウン記法
• [ ] 標準セクションの使い分け
• [ ] ドキュメントテストの作成
• [ ] リンクの作成方法
• [ ] ドキュメントの公開方法

次の章では、Cargoの高度な機能を学びます。