【Microsft Azure】最初の一歩-Azure DevOpsの利用
コル
テクてくブログ
【Doxygen】ドキュメント自動生成 プログラムと設計書の乖離を防ぎたい
コル
記事内に商品プロモーションを含む場合があります
こんにちは、コル（@bravecol）です。
いくつかの現場を経験してきてどの現場でも悩んでいるシーンを見かけるものがあります。それが設計書とプログラムが違うものになっていること。
「そんな機能設計書に載ってないやん！」なんて何度思ったことでしょうね。
ただ実際現場で仕事していると多いですよね？このシーン^^:
新規参入者には決して優しくない設計書たち。「システム開発は設計してから実装するんだよ」とは分かっていながらも「期限今日までね」とかいう上からの圧力がきて、そうはいかない事情が積み重なった集大成ですね(‘ω’)
今回はとある現場でドキュメンテーションツールDoxygenによって、極力ドキュメント管理の手間をかけないようにしている方々に出会って「Doxygenなかなかいいな」と思ったのでそのご紹介です。
目次
スポンサーリンク
Doxygenとは
ソースファイルのコメントから文書を自動生成するドキュメンテーションツールです。
執筆時点では対応言語として C++、C、Java、Objective-C、Python、IDL (Corba、Microsoft 風)、Fortran、VHDL、PHP、C# に対応しています。
メリットは主に下記2点。
- ドキュメントとソースコードの一貫性を保つことができる
- 要素間の関係が内包・依存図、継承図、 コラボレーション図により視覚化できる
Excelなどにより人が書くわけではなくプログラムによる自動生成のためソースコード変更時にドキュメントの修正も一緒に行える点が僕は好きだなと感じました。
またグラフの構造を画像ファイルへ出力するGraphvizもインストールすることでUML表現などが可能となります。
Doxygen準備（Windows）
必要資材ダウンロード
まずはDoxygenをダウンロードしましょう。
Doxygen公式サイトよりexeをダウンロードします。
次にGraphvizダウンロードしましょう。
同じくGraphviz公式サイトよりexeをダウンロードします。
インストールに関してはどれもデフォルトで大丈夫です。
僕が実施したときは下記のバージョンでした。
- doxygen-1.9.2
- stable版 graphviz-2.49.3
インストール手順は迷うことがなさそうなのでキャプチャは割愛します。
PATHに追加
自動生成時doxygenコマンドで行う必要があるため、環境変数にdoxygenを追加しましょう。
「Windowsのシステムプロパティ」もしくは「sysdm.cpl」にて環境変数設定を開き追加します。
「echo %PATH%」で見えれば何でもいいんですけどbinまでのパスを通すことが重要です。
C:\Program Files\doxygen\binパス追加が出来るとdoxygenコマンドが実行できるようになります。
インストール確認
それではインストールできたか確認しましょう。コマンドプロンプトを開いて下記を入力します。
> doxygen -v
1.9.2 (caa4e3de211fbbef2c3adf58a6bd4c86d0eb7cb8)バージョン情報が出力されれば無事準備完了です。
Doxygen準備（MacOS）
後日記載します。 2022/11/16更新
下記の通りIntel版だけでなくApple Siliconも対応していました（Homebrew公式サイト）
ここではHomebrewで実施していきます。Homebrewの各用語の意味とか全体像とかまとめて下さってる方がいたので参考として貼っておきます。イメージがつきやすくて助かりました^^
あわせて読みたい
Homebrew完全に理解した
Homebrewでインストール
まずはdoxygenインストールです。
searchでパッケージ検索、installでインストール実行できます。
$ brew search doxygen
==> Formulae
doxygen
==> Casks
doxie doxygen実際にインストールしてみます。
（しばしMacでの開発サボっていたので、いくつか不要なログも出てますがお許しください^^;）
$ brew install doxygen
Running `brew update --auto-update`...
==> Auto-updated Homebrew!
Updated 2 taps (homebrew/core and homebrew/cask).
==> New Casks
rapidapi
You have 3 outdated casks installed.
You can upgrade them with brew upgrade
or list them with brew outdated.
Warning: Treating doxygen as a formula. For the cask, use homebrew/cask/doxygen
==> Downloading https://ghcr.io/v2/homebrew/core/doxygen/manifests/1.9.5-1
######################################################################## 100.0%
==> Downloading https://ghcr.io/v2/homebrew/core/doxygen/blobs/sha256:1d601108785ac9543bd7708aa2f13707f8d76efdf40211088dedcd187d6eff3a
==> Downloading from https://pkg-containers.githubusercontent.com/ghcr1/blobs/sha256:1d601108785ac9543bd7708aa2f13707f8d76efdf40211088dedcd18
######################################################################## 100.0%
==> Pouring doxygen--1.9.5.monterey.bottle.1.tar.gz
🍺 /usr/local/Cellar/doxygen/1.9.5: 9 files, 19.2MB
==> Running `brew cleanup doxygen`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).doxygenのインストールを確認します。
$ doxygen -v
1.9.5次にGraphvizをインストールします。
$ brew install graphviz
==> Downloading https://ghcr.io/v2/homebrew/core/jasper/manifests/3.0.6_2
######################################################################## 100.0%
・・・・
（中略）
・・・・
==> Installing graphviz
==> Pouring graphviz--7.0.1.monterey.bottle.tar.gz
🍺 /usr/local/Cellar/graphviz/7.0.1: 328 files, 12.7MB
==> Running `brew cleanup graphviz`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).以上で必要なものは揃いました^^
Doxygen使い方
準備が出来たらまずは設定ファイルが必要になりますので作成していきます。こちらの公式マニュアルに沿って進めていきます。
まずは設定ファイルを下記で作成
> doxygen -g
Configuration file 'Doxyfile' created.
Now edit the configuration file and enter
doxygen
to generate the documentation for your project以上でコマンド実行した箇所にDoxyfileというファイルが出来上がります。
次にこの設定ファイルを指定して実行します。
> doxygen Doxyfile
Doxygen version used: 1.9.2 (caa4e3de211fbbef2c3adf58a6bd4c86d0eb7cb8)
Searching for include files...
Searching for example files...
・・（中略）・・
finalizing index lists...
writing tag file...
Running plantuml with JAVA...
lookup cache used 0/65536 hits=0 misses=0
finished...以上で終了です。意外と簡単に出力できます。
実行した結果index.htmlがhtmlフォルダに生成されます。
このHTMLが自動生成されたドキュメントです。
空のソースコードで実行したので中身なにもありませんが、ソースコメントをきちんと入れていけば相関図や継承図なども見えるようになります。
まとめ
今回はドキュメンテーションツールDoxygenについて記載しました。
開発規模やルールにもよりますが、極力ソースコードと乖離のないドキュメントを残したい場合に有効なツールだと思います。特にクラス定義など相関関係が分かる点においてはかなり助かります。
たいていどの現場でもExcelを用いてドキュメント管理してますけど、いい加減これをやめたいと何度も感じてます。そうは言いつつExcelを使わないといけない場面が多く、Excelの資料作りがうまくなっていく一方なんですけどね(笑)
使う場面を見極めつつ、極力開発者の負担を減らす、開発効率およびスピードを上げれるようにしていきたいと感じました。
ご一読ありがとうございました。
Appendix
・参考リンク
| Doxygen公式サイト | http://www.doxygen.jp/ |
| Graphviz公式サイト | https://graphviz.org/ |
| Homebrew Formulae公式サイト | https://formulae.brew.sh/formula/doxygen |
スポンサーリンク
運営者
ウェディングプランナーからエンジニアへ異業種転職し、家族と田舎のとある村でリモートワークメインで生活中。今はフリーランスエンジニアとしてJava/Python/Go/Reactなどが経験多め。子育てとコーディングを巧みに両立する「忍者スタイル」でスローライフと気になる技術を日々探求中！たまに妻から「ボヤッキーみたい」と笑われながらも、技術やガジェット関連をテーマにブログを更新しています。
