はじめに

本記事はシリーズ「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スタイル）と、関数・クラス・構造体・マクロ・ファイルヘッダそれぞれの実践的な記載例を紹介します。

シリーズ次回：【Doxygen実践#2】C/C++向けコメント記法と実践的な記載例