UML в Javadoc через maven+umlgraph


Где-то год назад писал про различные UML-редакторы.
К сожалению, ситуация толком не изменилась, пока действительно удобного на 100% для себя инструмента для создания UML-диаграмм не нашел.
UMLet – хорошо спасает в 80% случаев для быстрого прототипирования, но иногда его не хватает.

Сейчас речь пойдет не о нем, а о UMLGraph.
Это инструмент, который позволяет осуществлять декларативный способ рисования uml-диаграмм. Другими словами UML диаграммы создаются в текстовом виде, а не рисуется мышкой. Некоторым программистам (в частности мне) работать с текстом несколько удобней, чем с мышкой и со множеством графических объектов.

Возможностей у UMLGraph довольно много, но лично меня интересовали только следующие его возможности:

1. Рисование только диаграмм классов. Использование umlgraph для создания диаграмм последовательности, развертывания и т.д. мне не интересно.
2. Встраивание полученных диаграмм в JavaDoc.
3. Связка с maven-ом.

В результате некоторых манипуляций, можно получить следующий результат:

Что нужно для этого сделать:
1. Необходимо установить Graphiz. Это утилита для рисования различных диаграмм, через нее будем создавать итоговые рисунки.

Если у вас Windows, то для этого нужно:
– Зайти на сайт http://www.graphviz.org/.
– Выбрать пункт Download.
– Прочитать лицензию, если все ОК – нажать “Agreе“.
– Выбрать дистрибутив под Windows и установить.

Если у вас например Ubuntu, то все намного проще! Поскольку graphviz есть в стандартных репах, то вы можете установить через apt:

sudo apt-get install graphviz

2. Прописать в pom.xml использование umlgraph


    ... 
    
        
            
                maven-javadoc-plugin
                
                  org.umlgraph.doclet.UmlGraphDoc
                  
                    org.umlgraph
                    doclet
                    5.1
                  
                  -views
                    -inferrel -inferdep -quiet -hide java.*
                    -collpackages java.util.* 
                    -qualify
                    -postfixpackage 
        	    -attributes 
		    -operations 
		    -types
                    -nodefontclassname "Arial"
                    -nodefontclassabstractname "Arial Italic"
                    -nodefontclasssize 10
                    -nodefontname "Arial"
                    -nodefontabstractname "Arial Italic"
                    -nodefontsize 10
                    -nodefonttagname "Arial Italic"
                    -nodefonttagsize 10
                    -nodefontpackagename "Arial Italic"
                    -nodefontpackagesize 10
                    -edgefontsize 10
                  
                  true
                
            
        
    
    ...

В additionalparam можно указать свои настройки, чтобы настроить отображение диаграмм на свой вкус и цвет. В этом примере я немного поигрался с шрифтами. Список возможных настроек можно посмотреть здесь: http://www.umlgraph.org/doc/cd-opt.html.

3. Проверить, что программы из Graphiz установлены и доступен. Например можно набрать для этого в командной строке:

dot --help

4. Запустить mvn site. Как обычно в папке target появится директория с документацией.
Выкладываю в для наглядности maven-овский проект umldemo.1.zip и
полученную в итоге документацию umldemo-apidoc.zip.

Пару полезных заметок:
1. Чтобы исключить класс из диаграммы можно использовать опцию @hidden (см. пример PostA.java)
2. Список возможных опций можно посмотреть здесь: http://www.umlgraph.org/doc/cd-model.html

UPD. В Java 8 усилились требования к оформлению Javadoc. Можно ее ослабить добавлением в additionalparam параметра -Xdoclint:none”.
Вот так:


    -Xdoclint:none
    -views 
    и т.д.

,
Любое использование либо копирование материалов или подборки материалов сайта, элементов дизайна и оформления допускается лишь с разрешения правообладателя и только со ссылкой на источник: programador.ru

Телеграм канал: @prgrmdr
Почта для связи: vit [at] programmisty.com