A Doclet is a sort of plugin to the javadoc
tool to modify the standard behaviour of generating documentation.
The UMLDoclet delegates to the 'Standard' doclet to generate
all the 'normal' output you are used to. Furthermore, it analyzes the
parsed code to produce UML diagrams of your classes and packages.
These UML diagrams can be produced both in a text-based
and image format (e.g. svg or png).
Javadoc generation can be integrated into many build systems such
as maven,
gradle or even ant.
ℹ️ Tip: The javadoc commandline becomes verbose rather quickly, please consider using one of the following build systems for your projects:
The commandline javadoc command is explained here by Oracle but the main syntax is as follows:
javadoc [packages|source-files] [options][@files]Suppose you have downloaded version 2.x of the UML doclet (umldoclet-2.x.jar).
Say you have a java project with sources under src and classpath dependencies on lib.
Run the following command to document your software package com.foobar
in the directory apidocs using the UML doclet:
javadoc -sourcepath src -classpath lib -d apidocs \
-docletpath umldoclet-2.x.jar -doclet nl.talsmasoftware.umldoclet.UMLDoclet \
com.foobarMaven builds have the advantage of dependency management to fetch the UML doclet as part of the rest of your build:
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.0.1</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
<configuration>
<doclet>nl.talsmasoftware.umldoclet.UMLDoclet</doclet>
<docletArtifact>
<groupId>nl.talsmasoftware</groupId>
<artifactId>umldoclet</artifactId>
<version>2.x</version>
</docletArtifact>
<additionalOptions>
<!--<additionalOption>...</additionalOption>-->
</additionalOptions>
</configuration>
</plugin>
</plugins>
</build>Please don't forget to change the 2.x above to the latest release (see top of this page).
❗ Note: Version 2 and higher uses the new Javadoc API from JDK 9 and above. To build with an older JDK, please use the latest 1.x version of this doclet
In gradle, the doclet and its dependency need to be declared. From there on, the configuration is the same as your regular JavaDoc configuration.
Using the gradle Kotlin DSL:
val umlDoclet: Configuration by configurations.creating
dependencies {
umlDoclet("nl.talsmasoftware:umldoclet:2.0.15")
}
configurations {
umlDoclet
}
tasks.javadoc {
source = sourceSets.main.get().allJava
val docletOptions = options as StandardJavadocDocletOptions
docletOptions.docletpath = umlDoclet.files.toList()
docletOptions.doclet = "nl.talsmasoftware.umldoclet.UMLDoclet"
docletOptions.addStringOption("additionalParamName", "additionalParamValue")
}Alternatively, using the gradle Groovy DSL:
apply plugin: 'java'
configurations {
umlDoclet
}
dependencies {
umlDoclet "nl.talsmasoftware:umldoclet:2.x"
}
javadoc {
source = sourceSets.main.allJava
options.docletpath = configurations.umlDoclet.files.asType(List)
options.doclet = "nl.talsmasoftware.umldoclet.UMLDoclet"
options.addStringOption "additionalParamName", "additionalParamValue"
}Please don't forget to change the 2.x above to the latest release (see top of this page).
Obviously, replace additionalParamName and additionalParamValue with the
additional options you require.
In ant, the javadoc task needs to be told to use the UML Doclet in a similar way.
<javadoc destdir="target/javadoc" sourcepath="src">
<doclet name="nl.talsmasoftware.umldoclet.UMLDoclet" pathref="umlDoclet.classpath">
<param name="additionalParamName" value="additionalParamValue"/>
</doclet>
</javadoc>Make sure a path reference is defined for umlDoclet.classpath pointing to the
umldoclet-2.x.jar. It may be a good idea to use Ivy in this case.
Replace additionalParamName and additionalParamValue with the name and value
of each additional parameter you need.
The UML doclet supports all options of the Standard doclet and adds some of its own.
To display all options, please run:
javadoc --help -docletpath umldoclet-2.x.jar -doclet nl.talsmasoftware.umldoclet.UMLDocletThe rest of this section lists various options that are specific to the UML doclet.
Base URL for the PlantUML server.
Bypass the built-in internal PlantUML version and
use a remote plantuml-server instead to generate UML diagrams.
You can locally run a plantuml-server using docker:
docker run -d -p 8080:8080 plantuml/plantuml-server:latestThis starts a local plantuml-server on port 8080,
so the plantuml-server URL will be: -plantumlServerUrl http://localhost:8080/
Please don't configure the central PlantUML server.
While it should technically work if you have internet access,
aside from being rather impolite to use someone else's server without asking,
it is also rather slow for generating UML in a large java project.
Only HTTP and HTTPS urls are supported.
By default, UML images are generated in the same directory as the corresponding HTML documentation for the class or package. Specifying an image directory will place all generated images in this single directory, which makes directly linking to them from javadoc comments easier in some cases.
By default .svg images are generated as they will be significantly smaller
in size than equivalent .png images and scale better. They are included as
svg objects in the documentation to enable links in the diagrams. To include
.svg as images in the documentation, please you can use the svg_img image format.
You can generate multiple images per diagram by specifying a comma-separated
list of formats or providing the option multiple times.
Since the package dependencies diagram was introduced to the UML doclet,
it can analyze these dependencies to verify there are
no cyclic package dependencies.
If any are found, javadoc will print a warning, listing the dependency cycles found between the packages.
This option makes the javadoc task fail by turning this warning into an error.
The default for this setting is false.