次の環境で、PlantUMLのUML図（シーケンス図）をJavadocコメントに貼る方法を調査する。
| OS |
Windows 10 Pro 1909 64bit 日本語版 |
| JDK |
Oracle JDK 8u241 Windows 64bit版 |
| NetBeans IDE |
8.2 日本語版 |
NetBeans IDEを起動し、Javaアプリケーションプロジェクトを新規作成する。
その際、パッケージ名： com.torutk.helloplantuml
メインクラス名： HelloPlantUml
とした。
あとで作業、特にNetBeansが生成したAnt定義ファイルへの変更を明確化するために、gitで履歴管理をする。
以下の手順で、gitリポジトリ管理下に置き、初期ファイルを登録する。
- [チーム]メニュー > [Git] > [リポジトリの初期化]
- [チーム]メニュー > [追加]
- [チーム]メニュー > [コミット]
plantuml.jar をダウンロードする。
https://sourceforge.net/projects/plantuml/
ダウンロードしたplantuml.jarの置き場所はいくつかある。
- プロジェクトルート直下にlibディレクトリを作成しそこに配置する。
- Antのインストール場所（ANT_HOME）の下にあるlibディレクトリに配置する。
- ユーザーのホームディレクトリの下に .ant/lib ディレクトリを作成しそこに配置する。
今回はNetBeans IDE 8.2に同梱されるAntのlibディレクトリに配置する。
C:\Program Files\NetBeans 8.2\extide\ant\lib\
次に、JavaのソースコードにPlantUMLのUML定義を記述する。今回はシーケンス図を記述する。
package com.torutk.helloplantuml;
/**
* ドキュメントコメントにPlantUMLの記述を行い、Javadocで生成したドキュメントにそのUML図を貼る。
*
* <img src="../../../images/HelloPlantUml.png"/>
* @author torutk
*
* @startuml
* Alice -> Bob: Authentication Request
* Bob --> Alice: Authentication Response
*
* Alice -> Bob: Another authentication Request
* Alice <-- Bob: another authentication Response
* @enduml
*/
public class HelloPlantUml {
- imgタグのsrcは、PlantUMLが生成する図の保管場所への相対パスを記述します。
パッケージが3段（com.torutk.helloplantuml）の場合は、3段階ディレクトリを上がってimagesを指定します。
上述のJavadocコメントはjavadoc実行時にエラーががんがん出ます。JDK 8で追加されたJavadocの検査doclintがかなり厳しいチェックをするようになったためです。javadocコマンドのオプション -Xdoclint:none を指定して回避します。NetBeansのAntでは、nbproject\project.propertiesファイルに記述します。
- javadoc.additionalparam=
+ javadoc.additionalparam=-Xdoclint:none
build.xml にPlantUML生成の定義を追加する。
<!-- task definition of PlantUML -->
<taskdef name="plantuml" classname="net.sourceforge.plantuml.ant.PlantUmlTask"/>
<!-- process PlantUML for source files -->
<target depends="-javadoc-build" name="javadoc-uml">
<mkdir dir="${dist.javadoc.dir}/images/"/>
<plantuml output="${basedir}/${dist.javadoc.dir}/images/" verbose="true">
<fileset dir="${src.dir}">
<include name="**/*.java"/>
<exclude name="**/*Test.java"/>
</fileset>
</plantuml>
</target>
- taskdefでは、plantuml.jarをANT_HOME/libに置いたのでclasspath指定は省略可
- targetでは、UML付きJavadocを生成するので 名前をjavadoc-umlとした
- 先にJavadocをビルドしてからUML図生成を行うので dependsに-javadoc-build （定義済みターゲット）を指定
- UML図を格納する場所をJavadoc生成先ディレクトリのimagesとするため、mkdirしておく
- plantumlのタスクを実行
- output属性には、出力先を固定するには絶対パスで記述する。相対パスで記述するとソースファイルのある場所からの相対ディレクトリにUML図を生成する（その方が便利なこともある）
Antのjavadoc-umlを実行
- 左側ペインで[ファイル]タブを選択、build.xmlを展開し、ターゲット javadoc-umlを右クリックし、[ターゲット実行]
- 警告がでますが、ビルド成功となればOK
- Javadocを表示すると、UMLシーケンス図が貼られたドキュメントが見れます
⇒ build.xmlを展開し、-javadoc-browse を選択し[ターゲット実行]
