DoxygenからPlantUMLを使う。
こんにちは、高木です。
今日は夏休みという方も多いのではないかと思いますが、みなさんいかがお過ごしでしょうか？
さて今回は、先日仕事をDoxygenとPlantUMLを使う機会がありましたので、自分自身の備忘録も兼ねてこのネタで投稿することにします。
ご存じない方もいらっしゃると思いますので、まずはDoxygenとPlantUMLについて簡単に紹介することにします。
Doxygenというのは、プログラムのソースコードを解析してドキュメントを自動生成してくれるツールです。
もともとはC++用だったのですが、どんどん対応言語が増えて、現在では、CやObjective-Cはもちろん、Java, C#, PHP, Python, さらにはFortranやTclやVHDLにまで対応しているという何でもありの状況です。
PlantUMLというのは、UMLをテキストベースで記述して、それを画像に変換するツールです。
UMLとしてはそんなに完全なものではありませんが、そんなに厳密な記法が求められる機会はそう多くないはずですので、多くの場合は重宝します。
DoxygenとPlantUMLはまったく別のツールですが、使いたくなる状況が重なることも少なくありません。
それであれば、これらのツールを連携して、Doxygenが生成したドキュメントにPlantUMLが生成した画像を埋め込みたくなるというものです。
ちょっと前までは、正式な形での連携方法はなかったのですが、Doxygenの最近のバージョンではPlantUMLを呼び出すための機能が搭載されているため、非常に簡単に連携させることができるようになっています。
DoxygenからPlantUMLを使うには、Doxyfile（Doxygenの設定ファイル）に、次の2つの変数を設定することから始まります。
- PLANTUML_JAR_PATH
- PLANTUML_INCLUDE_PATH
PlantUMLの記述で !include を使うのでなければ、PLANTUML_JAR_PATH を設定するだけでも十分です。
この設定さえしておけば、あとはDoxygen用のコメントの中で、たとえば次のように記述するだけでシーケンス図が書けてしまいます。
1 2 3 4 | @startuml NodeA->NodeB : リクエスト activate NodeB NodeA |
上の記述から生成された画像は下記のようになります。
クラス図などはDoxygenが生成してくれますが、シーケンス図はソースコードから自動生成するのはさすがに無理です。
ですので、必要なら自分で作成するしかないのですが、それをコメントとしてソースコードに埋め込むことができるというのは画期的です。
PlantUMLの記述は、可読性も決して悪くありません。
仮に生成された画像がなくても、テキストベースの記述を読むだけでシーケンスを把握することができるのです。
こんな便利なツールが無償で提供されているというのもうれしいことです。
機会があればどんどん有効活用していくべきではないでしょうか。