VSCodeでDoxygenを利用する方法について

2026年10月26日

VSCodeでDoxygenを利用すると、CやC++などのソースコードに記述したコメントをもとに、APIリファレンスやクラス一覧、関数一覧などのドキュメントを自動生成できます。

DoxygenそのものはVSCodeの機能ではないため、基本的にはDoxygen本体をPCへインストールし、VSCodeからコメントを記述したり、ターミナルからDoxygenを実行したりして利用します。

C/C++で利用する場合は、Microsoftが提供しているVSCodeのC/C++拡張機能を組み合わせることで、Doxygen形式のコメント入力も効率化できます。

Doxygenとは

Doxygenは、ソースコード内のコメントを解析してドキュメントを自動生成するツールです。

特にCやC++で広く利用されていますが、複数のプログラミング言語に対応しています。

たとえば、C++の関数に次のようなコメントを記述できます。

/**
 * @brief 2つの整数を加算する
 *
 * @param a 1つ目の整数
 * @param b 2つ目の整数
 * @return aとbを加算した値
 */
int add(int a, int b)
{
    return a + b;
}

Doxygenを実行すると、このコメントとソースコードを解析し、関数名、引数、戻り値、説明などを整理したHTMLドキュメントを生成できます。

Doxygenで生成できる主な情報

Doxygenでは、主に次のような情報をドキュメント化できます。

クラス一覧
関数一覧
メンバー変数
名前空間
ファイル一覧
継承関係
コラボレーション関係
呼び出し関係
APIの説明
引数や戻り値の説明

ライブラリやSDKなど、外部へ公開するAPIの仕様書を作成する用途にも適しています。

VSCodeでDoxygenを利用するために必要なもの

VSCodeでDoxygenを利用するときは、主に次の環境を用意します。

Visual Studio Code
Doxygen本体
VSCodeのC/C++拡張機能
必要に応じてDoxygen関連のVSCode拡張機能
必要に応じてGraphviz

基本的な構成は次のとおりです。

VSCode
  ↓
Doxygen形式のコメントを記述
  ↓
Doxygenを実行
  ↓
HTMLなどのドキュメントを生成

ここで重要なのは、VSCodeの拡張機能とDoxygen本体は別物である点です。

VSCode拡張機能はコメント入力やDoxygen実行を支援できますが、ドキュメント生成そのものは基本的にDoxygen本体が担当します。

Doxygenをインストールする

Windowsの場合

Windowsでは、Doxygen公式サイトからDoxygenをインストールできます。

インストール後、VSCodeのターミナルで次のコマンドを実行します。

doxygen --version

Doxygenのバージョンが表示されれば、正常にインストールされています。

コマンドが見つからない場合は、Doxygenの実行ファイルがあるディレクトリがPATH環境変数に登録されていない可能性があります。

その場合は、Doxygenのインストール先を確認し、必要に応じてPATHへ追加します。

macOSの場合

Homebrewを利用している場合は、次のコマンドでDoxygenをインストールできます。

brew install doxygen

インストール後は次のコマンドで確認します。

doxygen --version

Linuxの場合

UbuntuやDebian系Linuxでは、次のようにインストールできます。

sudo apt update
sudo apt install doxygen

インストール後は次のコマンドを実行します。

doxygen --version

バージョン番号が表示されれば準備完了です。

VSCodeにC/C++拡張機能を導入する

CやC++でDoxygenを利用する場合は、Microsoftが提供している「C/C++」拡張機能を導入しておくと便利です。

VSCodeの拡張機能画面を開き、「C/C++」と検索してインストールします。

この拡張機能では、IntelliSenseやコードナビゲーションだけでなく、Doxygen形式のコメント入力も支援されています。

Doxygenコメントを自動生成する

関数などの直前で、

/**

と入力してEnterキーを押すと、関数の引数や戻り値に応じてDoxygenコメントのひな形を生成できます。

たとえば、次の関数があるとします。

int add(int a, int b);

関数の直前で/**を入力してEnterキーを押すことで、次のようなコメントを作成しやすくなります。

/**
 * @brief
 *
 * @param a
 * @param b
 * @return
 */
int add(int a, int b);

なお、この機能はDoxygen本体ではなく、VSCodeのC/C++拡張機能によるコメント入力支援です。

Doxyfileを作成する

Doxygenでは、通常Doxyfileという設定ファイルを使用します。

VSCodeでプロジェクトを開き、ターミナルから次のコマンドを実行します。

doxygen -g

すると、カレントディレクトリに次のファイルが作成されます。

Doxyfile

たとえば、プロジェクト構成が次のようになっているとします。

my-project/
├─ src/
│  ├─ main.cpp
│  └─ calculator.cpp
├─ include/
│  └─ calculator.h
└─ Doxyfile

このDoxyfileを編集して、解析対象や出力形式を設定します。

Doxyfileの基本設定

Doxyfileには非常に多くの設定項目があります。

最初からすべてを変更する必要はありません。

まずは主要な設定だけ理解しておけば十分です。

プロジェクト名を設定する

PROJECT_NAME = "My Project"

PROJECT_NAMEには、生成するドキュメントに表示するプロジェクト名を指定します。

出力先を設定する

OUTPUT_DIRECTORY = docs

この場合、生成されたドキュメントはdocsディレクトリ以下に出力されます。

解析対象を指定する

INPUT = src include

この例では、srcとincludeをDoxygenの解析対象に指定しています。

サブディレクトリを再帰的に解析する

RECURSIVE = YES

RECURSIVE = YESにすると、INPUTで指定したディレクトリ以下のサブディレクトリも再帰的に解析します。

たとえば、次のような構成でも、

src/
├─ core/
├─ network/
└─ utils/

INPUT = srcとRECURSIVE = YESを設定しておけば、各サブディレクトリも解析対象になります。

HTMLを生成する

GENERATE_HTML = YES

HTML形式のドキュメントを生成する設定です。

DoxygenをWebブラウザで閲覧したい場合は有効にしておきます。

LaTeXを生成しない

HTMLしか必要ない場合は、次のように設定できます。

GENERATE_LATEX = NO

これにより、LaTeX形式の出力を無効化できます。

コメントのない要素も抽出する

EXTRACT_ALL = YES

EXTRACT_ALL = YESにすると、Doxygenコメントが記述されていない要素もドキュメントへ掲載しやすくなります。

既存プロジェクトのクラスや関数構造を確認するときには便利です。

ただし、EXTRACT_ALL = YESでは未ドキュメント要素に関する警告が抑制されます。

すべての公開APIにコメントが記述されているか確認したい場合は、

EXTRACT_ALL = NO

として運用するほうが適しています。

Doxygenでドキュメントを生成する

Doxyfileの設定が完了したら、VSCodeのターミナルで次のコマンドを実行します。

doxygen Doxyfile

カレントディレクトリにDoxyfileがある場合は、

doxygen

だけでも実行できます。

たとえば、Doxyfileに次のように設定した場合、

OUTPUT_DIRECTORY = docs
GENERATE_HTML = YES

一般的には次のようなディレクトリが生成されます。

docs/
└─ html/
   ├─ index.html
   ├─ classes.html
   ├─ files.html
   └─ ...

docs/html/index.htmlをブラウザで開けば、生成されたドキュメントを確認できます。

Doxygenコメントの基本的な書き方

`@brief`で概要を書く

@briefは、関数やクラスなどの概要を説明するために使用します。

/**
 * @brief ユーザー情報を取得する
 */

一覧画面などにも表示されるため、簡潔で分かりやすい説明を書くのがおすすめです。

`@param`で引数を説明する

関数の引数は@paramで説明できます。

/**
 * @param width 横幅
 * @param height 高さ
 */

CやC++では、引数の入出力方向を指定することもできます。

/**
 * @param[in] value 入力値
 * @param[out] result 計算結果
 */

主に次の指定があります。

@param[in]
@param[out]
@param[in,out]

入力専用なのか、出力用なのかを明示できるため、C言語のAPIなどで特に便利です。

`@return`で戻り値を説明する

戻り値がある関数では、@returnを使用します。

/**
 * @brief 年齢を取得する
 *
 * @return 年齢
 */
int getAge();

単純な型名だけでなく、戻り値が何を意味するのかを書くことが重要です。

`@retval`で戻り値ごとの意味を書く

戻り値がステータスコードになっている場合は、@retvalを利用できます。

/**
 * @retval 0 正常終了
 * @retval -1 エラー
 */
int initialize();

C言語でエラーコードを返すAPIなどでは特に便利です。

`@note`で補足を書く

補足情報を書く場合は@noteを利用できます。

/**
 * @note この関数はスレッドセーフではありません。
 */

`@warning`で注意事項を書く

重要な注意事項には@warningを使用できます。

/**
 * @warning NULLを渡さないでください。
 */

通常の説明とは区別して表示されるため、利用者に必ず確認してほしい内容を書くときに適しています。

クラスにDoxygenコメントを書く

クラスにもDoxygenコメントを記述できます。

/**
 * @brief 計算処理を行うクラス
 */
class Calculator
{
public:
    /**
     * @brief 2つの整数を加算する
     *
     * @param a 1つ目の整数
     * @param b 2つ目の整数
     * @return 加算結果
     */
    int add(int a, int b);
};

クラスとメソッドの両方にコメントを書くことで、APIドキュメントを階層的に整理できます。

ファイルにDoxygenコメントを書く

ファイル単位で説明を記述したい場合は、@fileを利用できます。

/**
 * @file calculator.h
 * @brief 計算機能の公開インターフェース
 */

特にCやC++では、グローバル関数、マクロ、typedef、enumなどを適切にドキュメント化するうえで、ファイル自体をドキュメント対象として認識させることが重要になる場合があります。

そのため、ヘッダーファイルや公開APIをまとめたファイルでは@fileを記述しておくと管理しやすくなります。

名前空間をドキュメント化する

C++のnamespaceにもコメントを記述できます。

/**
 * @brief 数学処理をまとめた名前空間
 */
namespace math
{
}

大規模なC++プロジェクトでは、クラス単位だけでなく名前空間単位でドキュメントを整理すると分かりやすくなります。

C++テンプレートを説明する

テンプレートパラメータには@tparamを使用できます。

/**
 * @brief 最大値を取得する
 *
 * @tparam T 比較対象の型
 * @param a 1つ目の値
 * @param b 2つ目の値
 * @return 大きい方の値
 */
template <typename T>
T maxValue(T a, T b)
{
    return a > b ? a : b;
}

テンプレートライブラリを作成する場合には特に重要なタグです。

Doxygen Documentation Generatorを利用する

VSCodeでDoxygenコメントの入力をさらに効率化したい場合は、「Doxygen Documentation Generator」のような拡張機能を利用できます。

この拡張機能では、関数のシグネチャをもとに、Doxygenコメントのひな形を生成できます。

たとえば、

int add(int a, int b);

に対して、次のようなコメントを作成できます。

/**
 * @brief
 *
 * @param a
 * @param b
 * @return
 */
int add(int a, int b);

引数名を毎回手入力する必要がなくなるため、コメント作成の効率を高められます。

また、コメント形式や@param、@returnのテンプレートなどもカスタマイズできます。

Doxygen Runnerを利用する

ターミナルで毎回、

doxygen Doxyfile

と入力するのが面倒な場合は、Doxygen RunnerのようなVSCode拡張機能を利用する方法もあります。

Doxygen Runnerでは、VSCode上からDoxygenの生成処理を実行したり、生成したHTMLドキュメントを確認したりできます。

Doxygenの警告やエラーをVSCodeのProblemsパネルへ表示できるため、ドキュメントの不備も確認しやすくなります。

Doxyfileを固定する

複数のDoxyfileが存在するプロジェクトでは、使用する設定ファイルを明示しておくと便利です。

.vscode/settings.jsonに次のように設定できます。

{
    "doxygen_runner.configuration_file_override": "${workspaceFolder}/Doxyfile"
}

これにより、プロジェクトルートのDoxyfileを使用するよう指定できます。

VSCodeのTasksからDoxygenを実行する

Doxygen用の拡張機能を追加したくない場合は、VSCodeのTasks機能を利用する方法があります。

.vscode/tasks.jsonを作成し、次のように設定します。

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Doxygen: Generate Documentation",
            "type": "shell",
            "command": "doxygen",
            "args": [
                "Doxyfile"
            ],
            "group": "build",
            "problemMatcher": []
        }
    ]
}

その後、VSCodeのコマンドパレットから、

Tasks: Run Task

を選択し、

Doxygen: Generate Documentation

を実行すればドキュメントを生成できます。

プロジェクトメンバー全員で同じ生成方法を利用しやすいため、拡張機能への依存を減らしたい場合にも有効です。

Graphvizと連携して図を生成する

DoxygenはGraphvizと組み合わせることで、クラスや関数の関係を図として生成できます。

Graphvizをインストールしたうえで、Doxyfileを設定します。

Graphvizを有効にする

基本となる設定は次のとおりです。

HAVE_DOT = YES

HAVE_DOT = YESにすると、Graphvizのdotコマンドを利用した図の生成が可能になります。

クラス関係の図を生成する

たとえば次のように設定できます。

HAVE_DOT = YES
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES

CLASS_GRAPHはクラスの継承関係などを表示するための設定です。

COLLABORATION_GRAPHでは、クラス間の関連を図として確認できます。

呼び出し関係を生成する

関数の呼び出し関係を生成する場合は、次の設定があります。

CALL_GRAPH = YES
CALLER_GRAPH = YES

CALL_GRAPHでは対象関数が呼び出す関数を表示し、CALLER_GRAPHでは対象関数を呼び出している側を表示できます。

ただし、大規模プロジェクトでこれらを全面的に有効化すると、ドキュメント生成時間や出力サイズが増えることがあります。

そのため、通常は、

CALL_GRAPH = NO
CALLER_GRAPH = NO

としておき、必要な関数だけ@callgraphや@callergraphを使って個別に生成する方法もあります。

不要なディレクトリを解析対象から除外する

実際のプロジェクトでは、次のようなディレクトリをDoxygenで解析したくない場合があります。

build/
third_party/
vendor/
external/

その場合はEXCLUDEやEXCLUDE_PATTERNSを利用します。

たとえば、

EXCLUDE_PATTERNS = */build/* */third_party/*

と設定できます。

解析対象を適切に限定することで、生成時間の短縮や不要なドキュメントの混入防止につながります。

Doxygenが動かない場合の確認方法

`doxygen --version`を確認する

まずVSCodeのターミナルで次のコマンドを実行します。

doxygen --version

ここでエラーになる場合は、Doxygen本体がインストールされていないか、PATH設定に問題がある可能性があります。

Doxygenを直接実行する

VSCode拡張機能から実行できない場合は、まずターミナルから直接、

doxygen Doxyfile

を実行します。

CLIから正常に生成できるのであれば、Doxygen本体ではなくVSCode拡張機能側の設定に問題がある可能性があります。

反対にCLIでも失敗する場合は、DoxyfileやDoxygen本体の設定を確認します。

Doxyfileの設定を確認する

特に次の項目を確認します。

INPUT
RECURSIVE
FILE_PATTERNS
EXCLUDE
EXCLUDE_PATTERNS
OUTPUT_DIRECTORY

解析対象となるソースコードの場所が正しく指定されているかを確認することが重要です。

VSCodeでDoxygenを使うおすすめ構成

シンプルに利用するだけなら、次の構成で十分です。

VSCode
├─ C/C++拡張機能
├─ Doxygen本体
└─ Doxyfile

コメント生成をさらに効率化したい場合は、

VSCode
├─ C/C++拡張機能
├─ Doxygen Documentation Generator
├─ Doxygen本体
└─ Doxyfile

という構成が考えられます。

さらに、生成やプレビューまでVSCodeへ統合したい場合は、

VSCode
├─ C/C++拡張機能
├─ Doxygen Documentation Generator
├─ Doxygen Runner
├─ Doxygen本体
├─ Graphviz
└─ Doxyfile

という構成にすると便利です。

ただし、拡張機能はあくまで作業を効率化するための補助ツールです。

まずはターミナルで、

doxygen Doxyfile

を実行してドキュメントを正常に生成できる環境を構築しておくと、トラブルが発生した際にも原因を切り分けやすくなります。

まとめ

VSCodeでDoxygenを利用する場合は、まずDoxygen本体をインストールし、プロジェクトルートで、

doxygen -g

を実行してDoxyfileを作成します。

その後、

INPUT = src include
RECURSIVE = YES
GENERATE_HTML = YES
GENERATE_LATEX = NO

などを設定し、

doxygen Doxyfile

を実行すればHTML形式のドキュメントを生成できます。

CやC++では、VSCodeのC/C++拡張機能を利用することで、/**と入力してEnterキーを押すだけでDoxygenコメントのひな形を生成できるため、コメント作成も効率化できます。

さらに、Doxygen Documentation GeneratorやDoxygen Runnerを利用すれば、コメント生成、ドキュメント生成、プレビューなどをVSCodeへ統合できます。

クラス関係や呼び出し関係を図として確認したい場合は、Graphvizを導入してHAVE_DOTやCLASS_GRAPHなどを設定する方法も有効です。

実務では、まずDoxygen本体をCLIから正常に実行できる環境を作り、そのうえでVSCodeの拡張機能を補助的に利用する構成にすると、環境依存のトラブルを減らしやすくなります。

以上、VSCodeでDoxygenを利用する方法についてでした。

最後までお読みいただき、ありがとうございました。

よかったらシェアしてね！

URLをコピーしました！

URLをコピーしました！