はじめに

お客様に提案をしているときの会話です。

お客様：「詳細設計書は作りますか」
私：「昔ながらの詳細設計（ロジックを日本語で書くもの）は作りません。クラス図とか、シーケンス図は複雑であれば作りますが、今回のシステムはそこまで必要なものはないものなので、割愛しようと思っています。」
お客様：「保守をお願いするかどうか未定なので、場合によっては引継ぎのために作ってもらうかもしれません」
私：「・・・・」

といった感じで、私がこの業界に入った30年前は、確かにプログラムを作る前に、詳細設計書と呼ばれるプログラムを日本語で書いていました。
最近、詳細設計と呼ばれるものを作った記憶がなく、無駄なものは作りたくないなぁという思いから、コードから自動生成できないかなと思って、いろいろ試してみました。

Doxygenって

いろいろ調べてみると、Doxygen にたどり着きました。

色々な言語に対応した、ドキュメントジェネレータです。アウトプットもHTMLだけでなくMarkdownや、PDF、Wordでも出力できるようです。

また、Windows版、Linux版、Mac版といろんな環境で利用できるように準備されています。

やってみよう

インストール

とりあえず、今回はWSL上のUbuntuでやってみようと思います。
doxygenが本体で、graphvizはクラス図とかを生成するために利用します。

sudo apt install doxygen
sudo apt install graphviz

これでバージョン確認。2024/7/1時点で、1.8.17となりました（最新は、1.11.0）のようですが、やりたいことはできそうなので、このバージョンでOKとします。

doxygen --version

Doxyfileを作る

Doxygenを実行するためには、Doxyfileという設定ファイルが必要です。まずはひな形を生成します。

doxygen -g

Doxyfileができたら、以下のような修正を加えます。
設定値については、Doxygenの公式を参照するとよりよいと思います。

-OUTPUT_DIRECTORY       =
+OUTPUT_DIRECTORY       = "docs"

-OUTPUT_LANGUAGE        = English
+OUTPUT_LANGUAGE        = Japanese

-OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_OUTPUT_JAVA   = YES

-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES

-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES

-EXTRACT_PRIV_VIRTUAL   = NO
+EXTRACT_PRIV_VIRTUAL   = YES

-EXTRACT_PACKAGE        = NO
+EXTRACT_PACKAGE        = YES

-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES

-EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_CLASSES  = NO

-INPUT                  =
+INPUT                  = "src/main"

-RECURSIVE              = NO
+RECURSIVE              = YES

-REFERENCED_BY_RELATION = NO
+REFERENCED_BY_RELATION = YES

-REFERENCES_RELATION    = NO
+REFERENCES_RELATION    = YES

-ALPHABETICAL_INDEX     = YES
+ALPHABETICAL_INDEX     = NO

-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO

-UML_LOOK               = NO
+UML_LOOK               = YES

-UML_LIMIT_NUM_FIELDS   = 10
+UML_LIMIT_NUM_FIELDS   = 50

-TEMPLATE_RELATIONS     = NO
+TEMPLATE_RELATIONS     = YES

-CALL_GRAPH             = NO
+CALL_GRAPH             = YES

-CALLER_GRAPH           = NO
+CALLER_GRAPH           = YES

-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg

-DOT_GRAPH_MAX_NODES    = 50
+DOT_GRAPH_MAX_NODES    = 100

設定項目	説明
OUTPUT_DIRECTORY	ドキュメントの出力ディレクトリ。
OUTPUT_LANGUAGE	ドキュメントの出力言語。
OPTIMIZE_OUTPUT_JAVA	Java向けに出力を最適化するかどうか。
EXTRACT_ALL	全てのメンバーを抽出するかどうか。
EXTRACT_PRIVATE	プライベートメンバーを抽出するかどうか。
EXTRACT_PRIV_VIRTUAL	プライベートな仮想メンバーを抽出するかどうか。
EXTRACT_PACKAGE	パッケージメンバーを抽出するかどうか。
EXTRACT_STATIC	スタティックメンバーを抽出するかどうか。
EXTRACT_LOCAL_CLASSES	ローカルクラスを抽出するかどうか。
INPUT	ソースファイルの入力ディレクトリ。
RECURSIVE	入力ディレクトリを再帰的に検索するかどうか。
REFERENCED_BY_RELATION	被参照関係を生成するかどうか。
REFERENCES_RELATION	参照関係を生成するかどうか。
ALPHABETICAL_INDEX	アルファベット順の索引を生成するかどうか。
GENERATE_LATEX	LaTeX形式のドキュメントを生成するかどうか。
UML_LOOK	UMLスタイルの図を生成するかどうか。
UML_LIMIT_NUM_FIELDS	UML図に表示するフィールドの最大数。
TEMPLATE_RELATIONS	テンプレートの関係を表示するかどうか。
CALL_GRAPH	呼び出しグラフを生成するかどうか。
CALLER_GRAPH	呼び出し元グラフを生成するかどうか。
DOT_IMAGE_FORMAT	DOTグラフの出力フォーマット。
DOT_GRAPH_MAX_NODES	DOTグラフに表示する最大ノード数。

コメントの書き方

コメントの書き方はほぼJavadocと同じです。

クラスのコメント

/**
 * @brief デモ用のシンプルなクラス。
 *
 * このクラスには2つの整数を加算するメソッドが含まれています。
 */

メソッドのコメント

/**
 * @brief 2つの整数を加算します。
 *
 * このメソッドは2つの整数を入力として受け取り、その合計を返します。
 *
 * @param x 加算する最初の整数。
 * @param y 加算する二番目の整数。
 * @return 2つの整数の合計。
 */

その他コメントの一覧は以下の通り

コメント形式	説明
`@brief`	簡潔な説明を記述します。1行で概要を説明するのに適しています。
`@details`	詳細な説明を記述します。複数行に渡って、より具体的な情報を提供します。
`@param`	メソッドの引数を説明します。
`@return`	メソッドの戻り値を説明します。
`@file`	ファイルの説明を記述します。
`@author`	作者の名前を記述します。
`@version`	バージョン情報を記述します。
`@date`	日付を記述します。
`@see`	参照リンクを記述します。
`@deprecated`	非推奨であることを通知します。

生成する

以下のコマンドで、生成できます。

doxygen

作成されたドキュメントの一部

docs¥html配下にindex.htmlが作成されるので、それを参照してください。

こんな感じのドキュメントが生成されます。
シーケンス図がないので、処理の流れまでは分かりませんが、関連しているクラスまで
理解することができます。

終わりに

本当はシーケンス図までほしいのですが、さすがにそこまでは自動生成できませんした。
現状、シーケンス図も含めるためには、PlantUMLを使う方法があるようです。コメントにPlantUMLのDSLを書けばよいようなので、今度やってみようと思います。