プロジェクト

全般

プロフィール

調査 #104

未完了

調査 #100: Javadocで生成するドキュメントにUML図を埋め込む方法を調査する

Javadocで生成するドキュメントにPlantUMLで記述したUML図を埋め込む方法を調査する

高橋 徹 さんが約4年前に追加. 約4年前に更新.

ステータス:
進行中
優先度:
通常
担当者:
カテゴリ:
-
対象バージョン:
-
開始日:
2020/02/24
期日:
2020/03/01 (4年以上 遅れ)
進捗率:

50%

予定工数:

説明

調査目的:JavaソースファイルのコメントにPlantUMLツール用の言語(テキスト)を記述し、それから生成したUML図(シーケンス図、クラス図など)をJavadocで生成するドキュメントに含めたい

調査結果:

  • [#104-2] に JavadocでPlantUMLの図を生成しドキュメントに貼る手順を記載。

課題:

  • imgタグにパッケージの深さに応じた相対パスを記載するのは億劫、doc-filesに生成するようにしたい
    ⇒ 解決[#104-4]
  • 独自のAntターゲットを実行するのは面倒
    ⇒ 解決[#104-5]
  • PNGではなくSVGを生成
    ⇒ 解決[#104-7]
  • javadoc-umlビルド後、ブラウザに表示するところまで自動化したい
    ⇒ 解決[#104-6]
  • Windows上でUTF-8でソースコードを記述した際、PlantUMLの図で文字化け
    ⇒ 解決[#104-9]
  • javadoc実行時にplantumlの記述が警告にならないようにしたい
    ⇒ 未解決(試行失敗 [#104-8])

完了条件:入手物、生成手順、サンプルをWikiに記載する。


ファイル

umlsequence-1.png (46.1 KB) umlsequence-1.png シーケンス図が貼られたJavadoc 高橋 徹, 2020/02/24 22:16
create_shortcut_toolbar-1.png (13.8 KB) create_shortcut_toolbar-1.png ショートカットの作成 ツールバー・ボタンの追加(1) 高橋 徹, 2020/02/24 23:21
create_shortcut_toolbar-2.png (15.1 KB) create_shortcut_toolbar-2.png ショートカットの作成 ツールバー・ボタンの追加(2) 高橋 徹, 2020/02/24 23:21
create_shortcut_toolbar-3.png (11.7 KB) create_shortcut_toolbar-3.png ショートカットの作成 ツールバー・ボタンの追加(3) 高橋 徹, 2020/02/24 23:21

高橋 徹 さんが約4年前に更新

javaソースコードのコメントにPlantUMLのUML記述を記載し、Antでビルドする方法が次のドキュメントにあり。
https://plantuml.com/ja/ant-task

NetBeans IDEのAntプロジェクトで上述のAntタスクを使用してJavadocコメントにPlantUMLで生成したUML図を貼る方法が次のドキュメントにあり。
http://randomthoughtsonjavaprogramming.blogspot.com/2012/02/plantuml-and-netbeans.html

Javadoc形式のコメントに、PlantUMLが生成する図(画像ファイル)をimgタグで参照するよう記載し、javadoc生成時にPlantUMLで図を生成するというもの。

高橋 徹 さんが約4年前に更新

次の環境で、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 を選択し[ターゲット実行]

高橋 徹 さんが約4年前に更新

javadocで生成したドキュメント例。シーケンス図が貼られている。

umlsequence-1.png

高橋 徹 さんが約4年前に更新

imgタグにパッケージの深さに応じた相対パスではなくdoc-filesに生成するようにしたい

Javaソースコードコメントには次のように記述する。

- * <img src="../../../images/HelloPlantUml.png"/>
+ * <img src="doc-files/HelloPlantUml.png"/>

build.xmlの定義を修正

     <target depends="-javadoc-build" name="javadoc-uml">
-        <mkdir dir="${dist.javadoc.dir}/images/"/>
-        <plantuml output="${basedir}/${dist.javadoc.dir}/images/" verbose="true">
+        <plantuml output="./doc-files/" verbose="true">
             <fileset dir="${src.dir}">
                 <include name="**/*.java"/>
                 <exclude name="**/*Test.java"/>
             </fileset>
         </plantuml>
     </target>

高橋 徹 さんが約4年前に更新

独自のAntターゲットを実行するのは面倒

  • 左側ペインで[ファイル]タブを選択、build.xmlを展開し、javadoc-umlを右クリック > [ショートカットを作成]
    ウィザードが表示されるので、メニューなりツールバーに追加する
    以下はツールバーへの追加設定例

create_shortcut_toolbar-1.png

create_shortcut_toolbar-2.png

create_shortcut_toolbar-3.png

高橋 徹 さんが約4年前に更新

javadoc-umlビルド後、ブラウザに表示するところまで自動化したい

build.xmlでjavadoc-umlターゲットの最後に-javadoc-browseターゲットを呼び出すantcallを追加します。

         </plantuml>
+        <antcall target="-javadoc-browse"/>
     </target>

高橋 徹 さんが約4年前に更新

PNGではなくSVGを生成

build.xmlで、plantumlタスクの属性 format に"svg"を指定します。

-        <plantuml output="./doc-files/" verbose="true">
+        <plantuml output="./doc-files/" format="svg" verbose="true">

高橋 徹 さんが約4年前に更新

javadoc実行時にplantumlの記述が警告にならないようにしたい

Javadocのドキュメントコメント内にplantumlの記述をすると、

  • @startumlや、@endumlが未定義タグとして警告
  • 大なり・小なり記号(<、>)が警告(エラー)

などがあります。

そこで、plantumlの記述をドキュメントコメントではなくjavadoc処理対象外のブロックコメントに記述します。
以下はダメ

/**
 * ドキュメントコメントにPlantUMLの記述を行い、Javadocで生成したドキュメントにそのUML図を貼る。
 * 
 * <img src="doc-files/HelloPlantUml.svg"/>
 * @author toru
 */ 
/* @startuml
 * Alice -> Bob: Authentication Request
 * Bob --> Alice: Authentication Response
 * 
 * Alice -> Bob: Another authentication Request
 * Alice <-- Bob: another authentication Response
 * @enduml
 */
public class HelloPlantUml {

高橋 徹 さんが約4年前に更新

高橋 徹 さんが約4年前に更新

Windows上でUTF-8でソースコードを記述した際、PlantUMLの図で文字化け

Windows日本語版のデフォルト文字コードはWindows-31J(シフトJIS系)のため、ソースコードをUTF-8で記述していると、ASCII文字以外の文字がPlantUMLの生成した図で文字化けしてしまう。

そこで、明示的に文字コードを指定する。

- <plantuml output="./doc-files/" format="svg" verbose="true">
+ <plantuml output="./doc-files/" format="svg" verbose="true" charset="${source.encoding}">
  • source.encoding は、project.properties の中で定義されている

他の形式にエクスポート: Atom PDF