ソースコードからクラスや関数など、仕様をドキュメントとして自動生成してくれる便利ツールがいくつか存在します。
直近のプロジェクトで、これらの調査を行っていたため、まとめを残しておきます。
本記事では、広く使われている 「Doxygen」 についてです。
前提条件
- VisualStudioで
C#を使って開発中 -
windowsで使いたい - ソースコードにコメントは記載済み
概要
- ソースコードから自動的にドキュメントを生成するツール
- 言語、使用環境、出力できるフォーマットなど自由度が高い
基本情報
| 項目 | 説明 |
|---|---|
| 提供者 | Dimitri van Heesch. |
| ライセンス | GPL-2.0 https://www.doxygen.nl/license.html |
| 使用環境 | windows、Linux、Mac |
| 対応言語 | 主にC++ C、C#、Pythonなど |
| 出力フォーマット | html、LaTeX、mdなど https://doxygen.knowhow.jp/ |
使い方
-
上記のwebサイトからダウンロード・インストールする
-
任意のパスで設定ファイル（Doxyfile）を生成
doxygen -g
- Doxyfileを編集
- 次の例では、C#かつhtml出力しています
- デフォルトの差分を記載
| 項目 | 値 | 説明 |
|---|---|---|
| PROJECT_NAME | "My Document" | プロジェクト名 |
| INPUT | ./src | 対象とするソースコードのパス |
| FILE_PATTERNS | *.cs | 対象とするファイル、言語 |
| RECURSIVE | YES | サブディレクトリも対象にするか |
| EXTRACT_ALL | YES | すべてのクラス、関数、変数を対象にするか |
| EXTRACT_STATIC | YES | 静的関数も対処にするか ALLよりも優先される |
| OUTPUT_DIRECTORY | docs | 出力先ディレクトリ |
| GENERATE_HTML | YES | HTMLドキュメントを生成するか |
| GENERATE_LATEX | NO | LaTeX（PDF）ドキュメントを生成するか |
- ドキュメントを生成する
- 上記の例だと
docsフォルダが生成され、中にhtmlファイルが出力されます
- 上記の例だと
doxygen Doxyfile
doxygen # 省略も可
- 「Index.html」から閲覧できる
カスタマイズ
Graphvisと組み合わせて図も出力する
図形描画ツールの「Graphvis」と組み合わせると、クラスの継承や呼び出し関係を表現できます。
Graphvisをインストール後、次のようにDoxyfileを編集します。
dotファイルが出力されれば成功。
| 項目 | 値 | 説明 |
|---|---|---|
| HAVE_DOT | YES | Graphvizを有効化 |
| CALL_GRAPH | YES | 関数呼び出しグラフを生成 |
| CALLER_GRAPH | YES | 被呼び出し関係グラフを生成 |
| DOT_PATH | "xxxx\Graphviz\bin" | Graphvizのdotコマンドパス |
参考
- 設定一覧
- Doxgenの基本的な使い方
- 図の出力（Mac）
展望
具体例があるとわかりやすいため、
時間があればサンプルなど添付したいと思います。