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 コメントの書き方を習得することで、コードの変更に合わせてドキュメントを自動更新できるようになります。
@brief・@param などのコマンド一覧Doxyfile の設定項目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設定ファイル:
| ファイル | 説明 |
|---|---|
Doxyfile.part.calc |
C プロジェクト用 Doxygen 設定 |
Doxyfile.part.calc.net |
.NET プロジェクト用 Doxygen 設定 |
doxyfw/Doxyfile |
基本設定ファイル |
doxyfw/doxybook2-config.json |
Doxybook2 の設定 |
doxyfw/templates/ |
カスタム出力テンプレート |