DOCSEARCHbyAlgolia
Submit Docs

UMLDoclet

repository·main·Indexed 42 days ago

https://github.com/talsma-ict/umldoclet

A Javadoc Doclet that automates the generation of interactive SVG UML diagrams—including package dependency, package, and class diagrams—using PlantUML and embeds them directly into Java HTML documentation.

Tokens
2.5K
Snippets
5
Records
7
Agent score
4%

What's inside UMLDoclet

  1. Overview of UMLDoclet

    main

    UMLDoclet is a Javadoc Doclet that automatically generates UML diagrams using PlantUML and embeds them directly into your Java HTML documentation. It leverages existing Javadoc metadata to create visual representations of your project structure, making it easier to navigate and understand complex codebases.

    The tool generates three primary types of diagrams:

    • Package dependency diagrams: Visualizes how different packages in your project depend on one another. The Doclet can warn about or fail on cyclic package dependencies.
    • Package diagrams: Shows the internal structure and relationships within a specific package.
    • Class diagrams: Provides detailed views of classes and their relationships.

    By default, these diagrams are embedded as clickable SVG objects that link directly to the corresponding package or class documentation.

  2. Run UMLDoclet via Commandline

    main

    You can use the UMLDoclet directly with the standard javadoc command. You must specify the -docletpath pointing to the umldoclet-2.x.jar and the -doclet name as nl.talsmasoftware.umldoclet.UMLDoclet.

    Note: Version 2 and higher requires JDK 9 or above. For older JDKs, use the 1.x version of the doclet.

    javadoc -sourcepath src -classpath lib -d apidocs \
    -docletpath umldoclet-2.x.jar -doclet nl.talsmasoftware.umldoclet.UMLDoclet \
    com.foobar

  3. Configure UMLDoclet in Maven

    main

    Integrate UMLDoclet into your Maven build using the maven-javadoc-plugin. This allows Maven to manage the doclet dependency automatically. Set the <doclet> to nl.talsmasoftware.umldoclet.UMLDoclet and use <docletArtifact> to specify the umldoclet coordinates.

    <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>

  4. Requirements for using UMLDoclet

    main

    Before integrating UMLDoclet into your project, ensure you meet the following requirements:

    • Javadoc Version:
      • Use Javadoc version 9 or higher for the 2.x version of UMLDoclet.
      • If you are using older JDKs (Java 8 or earlier), use the 1.x version of UMLDoclet.
      • Note: If you are compiling Java 8 (or older) code using a more recent JDK (version 9+), you must use the 2.x version of UMLDoclet.
    • PlantUML: You do not need to install PlantUML separately; an Apache-licensed version of PlantUML is included within the umldoclet JAR file.

  5. Configure UMLDoclet in Ant

    main

    Use the <doclet> nested element within the <javadoc> task. You must provide the name of the doclet and a pathref that points to the classpath containing the umldoclet-2.x.jar.

    <javadoc destdir="target/javadoc" sourcepath="src">
    <doclet name="nl.talsmasoftware.umldoclet.UMLDoclet" pathref="umlDoclet.classpath">
        <param name="additionalParamName" value="additionalParamValue"/>
    </doclet>
</javadoc>

  6. Configure UMLDoclet in Gradle

    main

    In Gradle, you must create a custom configuration for the doclet to manage its dependencies, then apply those files to the javadoc task.

    Kotlin DSL: Use StandardJavadocDocletOptions to configure the docletpath and doclet name.

    Groovy DSL: Configure the javadoc task by setting options.docletpath and options.doclet.

    // 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")
}
    // 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"
}

  7. Reference: UMLDoclet Specific Options

    main

    The following options are specific to the UMLDoclet. You can view all available options by running javadoc --help -docletpath <path> -doclet nl.talsmasoftware.umldoclet.UMLDoclet.

    #### -plantumlServerUrl <url>
Base URL for the PlantUML server. Bypass the built-in internal PlantUML version and use a remote plantuml-server instead to generate UML diagrams.

#### -umlImageDirectory <image-dir>
Specifying an image directory will place all generated images in this single directory.

#### -umlImageFormat (_svg_ | svg_img | png | eps | none)
Specifies the image format. Default is `.svg`. You can specify multiple formats via a comma-separated list or by providing the option multiple times.

#### -umlCyclicPackageDependencies (ignore|warn|error)
Action to take when package-dependency cycles are detected. Default is `warn`. Use `error` to replace `-failOnCyclicPackageDependencies=true`.

#### -umlExcludePackageDependencies (true|false)
Exclude package dependency diagram from the overview Javadoc page. Default is `false`.

#### -umlExcludePackageDiagrams (true|false)
Exclude package diagrams from being automatically inserted into package Javadoc pages. Default is `false`.

#### -umlExcludeClassDiagrams (true|false)
Exclude class diagrams from being automatically inserted into class Javadoc pages. Default is `false`.

#### -umlRenderEmptyDiagrams (true|false)
Render diagrams, even when they are empty. Default is `false`.