# Doxygen

# 1 概要

Doxygen は、C/C++・Java・C# などのソースコード中のコメントを活用して、HTML や PDF などのドキュメントを自動生成するツールです。

Doxygen コメント形式は、通常のコメントに少し記法を加えるだけで利用でき、既存のコーディングスタイルを大きく変えずに導入できます。

このリポジトリの `doxyfw/` サブモジュールが Doxygen ベースのドキュメント生成フレームワークを提供しています。`prod/calc/` の C ソースコードに書かれた Doxygen コメントから XML を生成し、Doxybook2 で Markdown に変換して、最終的に HTML/docx として公開しています。`Doxyfile.part.calc`(C プロジェクト用)と `Doxyfile.part.calc.net`(.NET プロジェクト用)が Doxygen の設定ファイルです。

Doxygen コメントの書き方を習得することで、コードの変更に合わせてドキュメントを自動更新できるようになります。

# 2 習得目標

- `/** ... */` 形式の Doxygen コメントを書ける
- `@brief`・`@param`・`@return`・`@note` などの主要なコマンドを使用できる
- `Doxyfile` の基本的な設定項目を理解できる
- `doxygen Doxyfile` コマンドでドキュメントを生成できる
- XML 出力から Doxybook2 を経由して Markdown を生成する流れを理解できる
- `prod/calc/` の既存コメントを読んで Doxygen スタイルを把握できる

# 3 学習マテリアル

## 3.1 公式ドキュメント

- Doxygen マニュアル - Doxygen の公式マニュアル (英語)
  - コメントの書き方 - ドキュメントコメントの記述方法
  - コマンドリスト - `@brief`・`@param` などのコマンド一覧
  - 設定ファイルリファレンス - `Doxyfile` の設定項目

## 3.2 チュートリアル・入門

- Doxybook2 GitHub - Doxygen XML から Markdown に変換するツール

# 4 このリポジトリとの関連

## 4.1 使用箇所(具体的なファイル・コマンド)

Doxygen コメントの例 (`prod/calc/libsrc/calcbase/add.c` スタイル):

    /**
     * @brief 2つの整数を加算する
     *
     * @param[in]  a      加算する値1
     * @param[in]  b      加算する値2
     * @param[out] result 加算結果を格納するポインタ
     * @return CALC_SUCCESS 成功
     * @return CALC_ERR_NULL_POINTER result が NULL の場合
     */
    int add(int a, int b, int *result);

ドキュメント生成コマンド:

    cd doxyfw && make docs

設定ファイル:

Doxygen 設定ファイル一覧
ファイル | 説明
--- | ---
`Doxyfile.part.calc` | C プロジェクト用 Doxygen 設定
`Doxyfile.part.calc.net` | .NET プロジェクト用 Doxygen 設定
`doxyfw/Doxyfile` | 基本設定ファイル
`doxyfw/doxybook2-config.json` | Doxybook2 の設定
`doxyfw/templates/` | カスタム出力テンプレート

## 4.2 関連ドキュメント

- doxyfw/CLAUDE.md - doxyfw フレームワークの詳細ドキュメント
- Markdown(スキルガイド) - 生成後の Markdown の基礎知識
- Pandoc(スキルガイド) - Markdown から HTML/docx への変換