はじめに
本記事はシリーズ「C/C++組込み開発者のためのDoxygen実践ガイド」の第1回です。
- 第1回（本記事）：環境構築 — インストールからHTML出力まで
- 第2回：コメント記法と実践的な記載例
- 第3回：GitHub Actions + GitHub PagesによるCI自動ドキュメント生成
組込みソフトウェア開発において、「コードは読めばわかる」が通用するのは小規模・短期プロジェクトの間だけです。プロジェクトが大きくなるにつれ、こんな問題が起きていませんか？
- 担当者が変わるたびに引き継ぎコストが膨らむ
- 設計書とコードの内容が乖離しており、どちらが正しいかわからない
- 関数の仕様を調べるためにコードを読み解く時間が無駄にかかる
Doxygen は、ソースコード中の特定フォーマットのコメントから、HTML・PDF・LaTeXなどのリファレンスドキュメントを自動生成するツールです。コードとドキュメントを同一ファイルで管理することで、乖離を防ぎ、レビュー・引き継ぎ・新人教育のコストを大幅に削減できます。
本記事では、C/C++組込みプロジェクトへのDoxygen導入を検討しているリード・PM層を対象に、インストールから最初のHTML出力までを一通り解説します。
動作確認環境
| 項目 | バージョン |
|---|---|
| Doxygen | 1.9.8 |
| OS | Ubuntu 22.04 / Windows 11 / macOS 14 |
| 対象言語 | C / C++ |
1. Doxygenのインストール
Ubuntu / Debian系
sudo apt update
sudo apt install -y doxygen doxywizard graphviz
graphviz はクラス図・依存関係グラフの生成に使います。後述のDoxyfile設定で有効化できるので、合わせてインストールしておくことを推奨します。
Windows
Doxygen公式サイト からインストーラ（doxygen-X.X.X-setup.exe）を取得して実行します。
グラフ生成を使う場合は Graphviz公式サイト からも別途インストールし、dot.exe のパスを環境変数 PATH に追加してください。
macOS（Homebrew）
brew install doxygen graphviz
バージョン確認
doxygen --version
# 例: 1.9.8
2. Doxyfileの生成
Doxygenの設定はすべて Doxyfile という設定ファイルで管理します。プロジェクトルートで以下を実行すると、デフォルト設定のDoxyfileが生成されます。
cd /path/to/your/project
doxygen -g
生成直後のDoxyfileは約2,700行あり（バージョンにより異なる）、すべての設定項目がコメント付きで記載されています。ただし、最初から全部読む必要はありません。次のセクションで最低限触るべき項目に絞って解説します。
Doxyfileはプロジェクトのバージョン管理（Git）に含めることを強く推奨します。チームで同じ設定を共有でき、設定変更の履歴も追えるようになります。
3. Doxyfileの最低限設定
生成されたDoxyfileをエディタで開き、以下の項目を確認・修正します。
プロジェクト基本情報
PROJECT_NAME = "MyEmbeddedProject"
PROJECT_NUMBER = "1.0.0"
PROJECT_BRIEF = "○○制御ユニット ソフトウェアリファレンス"
OUTPUT_LANGUAGE = Japanese
OUTPUT_LANGUAGE を Japanese に設定すると、生成HTMLのUI文字列が日本語になります。
入力ファイルの設定
# ドキュメント化するソースの起点ディレクトリ
INPUT = ./src
# サブディレクトリも再帰的に探索する
RECURSIVE = YES
# 対象とする拡張子を明示する（デフォルトでC/C++は含まれるが明示が推奨）
FILE_PATTERNS = *.c *.cpp *.h *.hpp
出力ディレクトリ
OUTPUT_DIRECTORY = ./docs/doxygen
./docs/doxygen は、CIで自動生成する場合は .gitignore に追加しておくとよいでしょう。ローカル確認用に生成物をGitに含めたい場合はそのままでも構いません。
コメントのないシンボルも出力する
EXTRACT_ALL = YES
最初は YES にしておくと、コメントが不足している箇所も一覧できて便利です。チームへの定着後は NO に戻すことで「コメントなし＝ドキュメントに出ない」というルールを自然に運用できます。
グラフ生成（graphvizインストール済みの場合）
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
UML_LOOK = YES
COLLABORATION_GRAPH = YES
クラス継承図・関数呼び出しグラフが自動生成されます。大規模プロジェクトでは生成時間が増えるため、必要に応じて有効化してください。
4. サンプルコードで動作確認
以下のサンプルを src/motor_control.h として作成します（Doxygenコメントの詳細は第2回で解説します）。
/**
* @file motor_control.h
* @brief モーター制御モジュール
*/
#ifndef MOTOR_CONTROL_H
#define MOTOR_CONTROL_H
/**
* @brief モーターの回転方向
*/
typedef enum {
MOTOR_DIR_FORWARD, /**< 正転 */
MOTOR_DIR_REVERSE, /**< 逆転 */
MOTOR_DIR_STOP /**< 停止 */
} MotorDirection;
/**
* @brief モーターを指定速度・方向で駆動する
*
* @param[in] speed 回転速度 (0〜100 [%])
* @param[in] dir 回転方向
* @return 0: 正常終了, -1: パラメータ異常
*/
int Motor_Drive(int speed, MotorDirection dir);
/**
* @brief モーターを停止する
*/
void Motor_Stop(void);
#endif /* MOTOR_CONTROL_H */
HTML生成の実行
doxygen Doxyfile
完了すると ./docs/doxygen/html/index.html が生成されます。ブラウザで開いて確認しましょう。
# Linux
xdg-open ./docs/doxygen/html/index.html
# macOS
open ./docs/doxygen/html/index.html
# Windows（PowerShell）
Start-Process .\docs\doxygen\html\index.html
Motor_Drive 関数のページを開くと、@param・@return の内容がきれいに整形されて表示されているはずです。
5. よくあるトラブル
| 症状 | 原因と対処 |
|---|---|
dot: command not found |
graphvizが未インストール、またはPATHが通っていない |
| 日本語が文字化けする | ソースファイルをUTF-8で保存し、INPUT_ENCODING = UTF-8 をDoxyfileに設定する |
| ファイルが出力されない |
INPUT のパスが誤っている。絶対パスで試す |
| 関数が出力されない |
EXTRACT_ALL = YES を試す。staticな関数は EXTRACT_STATIC = YES も必要 |
まとめ
本記事では以下を実施しました。
- Doxygenのインストール（Ubuntu / Windows / macOS）
-
doxygen -gによるDoxyfileの生成 - 最低限触るべき設定項目の確認（
INPUT,RECURSIVE,EXTRACT_ALLなど） - サンプルC++コードでのHTML出力確認
次回は、チームで統一すべきコメント記法（Javadocスタイル）と、関数・クラス・構造体・マクロ・ファイルヘッダそれぞれの実践的な記載例を紹介します。