Giter Club home page Giter Club logo

uml-java-doclet's Introduction

Overview

Add UML diagrams (using PlantUML) to Javadocs. Extends the standard Java doclet.

Status

The doclet tool was completely changed in Java 9; uml-java-doclet will not work with any JDK later than 8.

This project is not maintained anymore, since for us it is not worth effort required to update it for later JDKs. However, if anyone wants to take it on, feel free to log any issues and I will do my best to answer.

Background

The inspiration for this project is better communication between the developers on my team. We want to follow the principles of DDD and Model-Driven Design (https://www.amazon.ca/dp/0321125215) and automatically generating class diagrams is a key part of that approach.

Diagrams

Generates three types of diagrams:

  • Overview: Shows all classes within all packages. Click on a class to get to the Javadoc for that class. Click on a package to get to the Javadoc for that package.
  • Package: Shows all of the classes within a package, and the relationships between them. Does not show relationships with classes outside the package.
  • Class: Shows all of the relationships with other classes. If the other class is in the same package, it is shown in yellow (default color). If in another package within the set of packages, it is shown in white. If the other class is outside any of the packages, it is shown in grey.

The relationships with other classes are determined by what the Javadoc API provides, which is from the attribute and method declarations for a class. Any usages that are buried within code will not be shown. If I think a relationship is important enough to be shown, I will make it explicit (e.g. add an attribute to the other class).

Layouts can appear strange. This is due to the use of GraphViz. Good enough for my purposes, although there are other options that are being explored (http://plantuml.sourceforge.net/qa/?qa=4842/graphviz-is-not-good-enough).

Dependencies

  • GraphViz (as required by PlantUML).
  • Java 8 (easy enough to backport to earlier versions).

NOTE: The doclet tool was completely changed in Java 9; uml-java-doclet will not work with any JDK later than 8.

Installing

Use http://jitpack.io to automatically build and install the JAR file. Add the JitPack repository to your POM:

<repositories>
	<repository>
	    <id>jitpack.io</id>
	    <url>https://jitpack.io</url>
	</repository>
</repositories> 

Note: Not published to Maven Central; this is a much easier alternative.

Generating Updated Javadocs

To generate UML diagrams for your own project, add the following to your POM:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>                                  
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.2.0</version>
            <configuration>
                <doclet>info.leadinglight.umljavadoclet.UmlJavaDoclet</doclet>
                <docletArtifact>
                    <groupId>com.github.gboersma</groupId>
                    <artifactId>uml-java-doclet</artifactId>
                    <version>1.1</version>
                </docletArtifact>
                <useStandardDocletOptions>true</useStandardDocletOptions>
                <additionalOptions>
                    <!-- Specify each diagram option here as an additionOption tag. -->
                </additionalOptions>
            </configuration>
        </plugin>
    </plugins>
</build>

Note: Version 3+ of the maven-javadoc-plugin uses the additionalOptions tag to specify additional javadoc tags. The previous additionalparam tag no longer works correctly. Be sure to upgrade your POMs accordingly.

Diagram Options

Options for the diagrams are specified as additionalOption tags in the POM.

Option Valid Values Default Description
-linetype polyline,spline,ortho ortho Types of lines to display on diagrams
-dependencies public,protected,package,private public What dependencies to explicitly show on the diagram
-package-orientation top-to-bottom,left-to-right top-to-bottom Layout of packages on package diagrams
-output-model true,false false Whether to output the details of the model (useful for debugging)
-puml-include-file free-form none Name of PUML file to include in every diagram PUML
-exclude-classes comma-separated none List of qualified class names to exclude from context diagrams
-exclude-packages comma-separated none List of qualified package names to exclude from context diagrams

Tips

Acknowledgments

Many thanks to the folks at PlantUML (https://github.com/plantuml/plantuml) for their fantastic support. Thanks to @bcopy for the pointer to jitpack.

License

Copyright 2016 Gerald Boersma

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

uml-java-doclet's People

Contributors

gboersma avatar hderuiter avatar huntertran avatar olivier-at-kineis avatar voruti avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

uml-java-doclet's Issues

syntax error with generics

When using some generics I get following error when viewing the generated javadoc TestGenerics.MyModelBuilder page;
... (skipping 12 lines) ...class "<b><size:14>TestGenerics.AbstractBuilder<P, MyModel, MyModelBuilder></b>\n<size:10>info.leadinglight.umljavadoclet" as info.leadinglight.umljavadoclet.TestGenerics.AbstractBuilderObjectTestGenerics.MyModelTestGenerics.MyModelBuilder<P>{}hide info.leadinglight.umljavadoclet.TestGenerics.AbstractBuilderObjectTestGenerics.MyModelTestGenerics.MyModelBuilder<P> fieldsSyntax Error?

Created a test model;
`package info.leadinglight.umljavadoclet;

import java.util.HashMap;
import java.util.Map;
import java.util.function.BiConsumer;
import java.util.function.Consumer;

public class TestGenerics {

Map<String,MyModel> result = new HashMap<>();

public static void main(String[] argu[]) {
	new TestGenerics().createValue("1").setValue("1VAL").build().createValue("2").setValue("2VAL").build().extendValue("1").setValue("1WAL-Override").build();
}

public MyModelBuilder<TestGenerics> createValue(String key) {
	return new MyModelBuilder<>(this, new MyModel(), (p,v) -> p.result.put(v.key, v)).setKey(key);
}

public MyModelBuilder<TestGenerics> extendValue(String key) {
	return new MyModelBuilder<>(this, result.get(key), (p,v) -> {});
}

public class MyModel {
	String key;
	String value;
}

public interface Builder<T> {
	T build();
}

/**
 * Abstract object builder with parent builder.
 *
 * @param <P> The parent builder.
 * @param <T> The object to build.
 * @param <B> The current builder.
 */
abstract public class AbstractBuilder<P, T, B> implements Builder<P> {
	private final P parent;
	private final T value;
	private final BiConsumer<P, T> parentBuilder;
	
	public AbstractBuilder(P parent, T value, BiConsumer<P, T> parentBuilder) {
		this.parent = parent;
		this.value = value;
		this.parentBuilder = parentBuilder;
	}
	
	@Override
	public final P build() {
		parentBuilder.accept(parent, value);
		return parent;
	}
	
	protected final B make(Consumer<T> mixer) {
		mixer.accept(value);
		return (B) this;
	}
}

public class MyModelBuilder<P> extends AbstractBuilder<P,MyModel,MyModelBuilder<P>> {
	public MyModelBuilder(P parent, MyModel value, BiConsumer<P, MyModel> parentBuilder) {
		super(parent, value, parentBuilder);
	}
	
	protected MyModelBuilder<P> setKey(String key) {
		return make(v -> v.key=key);
	}
	
	public MyModelBuilder<P> setValue(String value) {
		return make(v -> v.value=value);
	}
}

}
`
When put in src./test/java/..... and run javadoc:test-javadoc to have test case.

Java Doclet 9+ Support

In Java 9, the doclet tool was completely reworked and is not backwards compatible with version 8-.

Generics within Generics not Represented On Diagrams

Generics embedded within generic parameters are not represented well across all diagrams:

  • Fields show only the first level of generics, e.g. List<Optional<String>> shows up as List<Optional>.
  • A relationship with an embedded generic is not shown on the diagram, e.g. List<Optional<MyClass>> will not show a uses relationship with MyClass.
  • Specifying wildcards as generic parameters can be problematic when generating diagrams: can show as a separate package on a package diagram.

exclude classes

hi
i try to exclude some classes from appearing in the Diagram,depending on which annotation it has, and this could be solvedby creating function and call this function many times in deferant files
(ModelPackage.java,ontextDiagramPrinter.java,Model.java,ModelClass.java) and it works.
but in other hand i would like to do the same job using pom.xml parameters but unfortunately it didnt works please help me if you have an idea.
you could also check my work
Thanks
https://github.com/feras-om/uml-java-doclet/tree/master/src/main/java/info/leadinglight/umljavadoclet

Doclet failes with StringIndexOutOfBoundsException

I'm trying to generate documentation and gets error with version 1.0.0 published on the Central:

javadoc: error - In doclet class info.leadinglight.umljavadoclet.UmlJavaDoclet,  method start has thrown an exception java.lang.reflect.InvocationTargetException
java.lang.StringIndexOutOfBoundsException: String index out of range: -1
	at java.lang.String.substring(String.java:1967)
	at info.leadinglight.umljavadoclet.model.ModelPackage.parentPackageFullName(ModelPackage.java:62)
	at info.leadinglight.umljavadoclet.model.Model.isRootPackage(Model.java:87)
	at info.leadinglight.umljavadoclet.model.Model.rootPackages(Model.java:75)
	at info.leadinglight.umljavadoclet.printer.OverviewDiagramPrinter.generate(OverviewDiagramPrinter.java:20)
	at info.leadinglight.umljavadoclet.UmlJavaDoclet.generateOverviewDiagram(UmlJavaDoclet.java:173)
	at info.leadinglight.umljavadoclet.UmlJavaDoclet.start(UmlJavaDoclet.java:75)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:498)
	at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:310)
	at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:189)
	at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:366)
	at com.sun.tools.javadoc.Start.begin(Start.java:219)
	at com.sun.tools.javadoc.Start.begin(Start.java:205)
	at com.sun.tools.javadoc.Main.execute(Main.java:64)
	at com.sun.tools.javadoc.Main.main(Main.java:54)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.