talsma-ict / umldoclet Goto Github PK

View Code? Open in Web Editor NEW

231.0 10.0 32.0 94.6 MB

Automatically generate PlantUML diagrams in javadoc

License: Apache License 2.0

Java 99.99% Batchfile 0.01%

javadoc doclet plantuml diagram generator code-analysis uml

umldoclet's Introduction

UMLDoclet

Doclet for javadoc to automatically add UML diagrams to Java documentation.

Generate UML diagrams

The UML Doclet uses available javadoc metadata to automatically generate the following UML diagrams and embeds them in your HTML documentation. The diagrams are embedded as clickable SVG objects by default and link to package and class documentation where available.

Package dependency diagram

The UML Doclet will warn about (and optionally fail on) cyclic package dependencies.

The dependency diagram links to package documentation containing:

Package diagram

The package diagram links to class documentation containing:

Class diagram

(These examples are from the latest UML Doclet javadoc page. Please feel free to take a look to get an idea of the final result)

Requirements

To use the UML Doclet, the following is required.

Javadoc version 9 or higher.
For versions of javadoc from earlier JDKs, please use the latest 1.x UML Doclet version. If you compile your java 8 or older javadocs with a more recent JDK (Javadoc version 9 or higher), you need to use the 2.x version.
The UML Doclet, the usage page shows how. An apache-licensed version of PlantUML is already included in the umldoclet jar.

Releases

Released versions can be found in the maven central repository or on github.

Usage

Please see the separate usage page on how to use the UML Doclet in your own Java projects.

Feedback

We welcome new issues. Please search the current issues to avoid filing a duplicate.
If at all possible, please provide an example when sending in bugs. This will make fixing them that much easier!

Contributing

See the contribute page for this repository.

Thanks

First of all a big thanks to Arnaud Roques, the developer of the excellent PlantUML project without whom this project wouldn't exist!
And of course thank you for using UML Doclet. I hope it may be of benefit to your project!

License

Apache 2.0 license

umldoclet's People

Contributors

Stargazers

Watchers

umldoclet's Issues

Multi-version jar

JDK 9 introduced the multiversion jar concept.

This may provide a neat way to release a single jar that is the 2.x version, but contains the old 1.x javadoc api version.

Send images to a single directory

It is difficult to embed the images (package.jpg for example) in Javadoc because they cannot be located using <img...> tags from multiple locations (the overview pages and per-package pages).

The suggested solution is to send the images to a single directory with the image files having fully package qualified names, for example org.johnWorrell.mypackage.package.jpg.

Package dependencies

Properties are rendered inversely (e.g. <.. instead of ..> ).
Lines must be solid ( --> instead of ..> )

Document non-maven usage.

At least document how to use with:

gradle
commandline

Verify whether -umlIncludePackagePrivateClasses works as advertized

Looks like it may not always default to false correctly for package diagrams.

Variable method arguments get rendered as their 'single value' counterpart type.

Define an api that allows more fine-grained UML customization.

Requirements for this API:

It should be as 'thin' as possible and self-contained with no external dependencies so it can easily be published as small '.jar'.
At minimum, define a way to define a custom UML renderer for a particular class.

Add dependency diagrams showing all dependencies on package level.

Not quite sure what I meant by this in my initial ideas.
Probably this could mean an additional diagram as a variant to the current package.puml / class.puml creation that shows all dependencies instead of focussing on readability.

Let's play with it and see where that leads us.

Document new maven javadoc plugin setting

additionalparam becomes additionalOptions since maven-javadoc-plugin version 3.0.0

Add badges to README.

Badges for:

travis-ci build (depends on #31).
maven-central version.

Simplify classname within namespace.

If a class is rendered within a namespace, it is currently rendered using its fully qualified name (since that is easiest and pretty much always correct).

However, within a namespace, the namespace itself can (and arguably should) be left out.

Automatic inclusion in Standard documentation

It would be nice if Standard class documentation included appropriate diagrams automatically when using the doclet.

Note that this is currently already available, however requires custom <img> tags.

Log correct PlantUML version (string).

The new PlantUML version returns "1201715" as its version.
This should be "1.2017.15" instead.

getXyz() method with arguments is represented as property.

Example:
' +getDescriptionProviderFor(Class<?>): DescriptionProvider

Add github issue template

See https://help.github.com/articles/creating-an-issue-template-for-your-repository/

Document usage for initial release of this doclet.

Describe all the options and javadoc tags and where they can be used.

Add test coverage reporting

This involves the following steps:

Using a maven coverage tool such as jacoco
Figure out how to instrument the maven javadoc plugin to suit tools like jacoco!
Reporting to an online service such as coveralls.io
Adding a CI coverage badge to the README file.

How to integrate png or svg in javadoc html

Is there a way to integrate the resulting diagrams (png or svg) in the html generated?

Option to omit public default constructor if it is the only constructor specified.

I was thinking to enable it by default too.

class visibility does not work.

Package-protected classes are rendered the same as public classes in the package diagram.

They should either be marked differently or removed from the diagram altogether.
Their individual class-diagram can be generated normally of course.

Generics support

Generics are currently ignored.
The generic type information is valuable and should be included.

Usage documentation: parameter table is too wide for default github layout.

The table scrolls horizontally within the page in default github layout.

Improve support for annotations

Annotations currently extend java.lang.Annotation and are declared as abstract classes.

It might be better to create a specialized renderer for annotations and provide them with their own symbol instead of the A for abstract classes (use an @ if possible).

Include Plantuml rendering of .puml files to .png images if Graphviz is detected.

After creating all .puml diagrams, there should be a step where the doclet tries to locate graphviz and renders a .png image for each diagram.

Attain acceptable level of unit-test coverage.

This provides a safety net to prevent unnecessary regression bugs.
Also allows for easier refactoring of existing code.

Add custom tag support to Standard doclet to support @classdiagram javadoc

This depends on feature #11 to be implemented.

Think about the tagnames, as they provide the 'public api' from this doclet and we will have to keep supporting them no matter what.
Similarly, there could be an @packagediagram tag etc.

No dot executable found

I must be doing something wrong...In order to activate the doclet, I had to remove the execution from the suggested pom.xml configuration. Then after running 'mvn javadoc:javadoc', the generated PNG files contain the message "No dot executable found", but I have confirmed that dot.exe is in my PATH. What am I missing?

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.0.0</version>
<configuration>
<doclet>nl.talsmasoftware.umldoclet.UMLDoclet</doclet>
<docletArtifact>
<groupId>nl.talsmasoftware</groupId>
<artifactId>umldoclet</artifactId>
<version>1.0.17</version>
</docletArtifact>
<additionalOptions>
<additionalOption>-umlLogLevel DEBUG</additionalOption>
<additionalOption>-umlImageFormat PNG</additionalOption>
</additionalOptions>
</configuration>
</plugin>

Typo in usage example for gradle integration.

...
options.docletPath = configurations.umlDoclet.files.asType(List)
...

For the doclet to be found by gradle,
the correct setting must be a small letter "p" as in "options.docletpath".
Source:
https://docs.gradle.org/3.5.1/javadoc/org/gradle/external/javadoc/MinimalJavadocOptions.html#docletpath(java.io.File...)

Private inner classes get rendered by default.

Multiple improvements possible:

Obviously, don't render private inner classes
Mark innerclass relationship to parent with --+

Feature request: ability to influence the style of generated diagrams.

Hi,

I'd like to see the functionality added for influencing style changes to generated diagram.
For instance, a way to add "hide class circle" to the generated puml.

For the how of this request: If one could supply an "!include directive" to some location to this doclet, that would do the trick, I think.

Thanks in advance!

Kind regards,

Herman de Boer.

Sanitize and/or group the many settings for this doclet.

Furthermore, consider allowing per-package / class / method / field overrides through javadoc tags where applicable.

Additionally, at least add support for the settings used by the old legacy doclet.

Thirdly, check out the parameters of the Standard doclet, and see if these can serve as decent defaults (and whether that's desirable; I can imagine someone wanting to document the protected methods, but excluding them from the diagrams by default).

Improve release script

Make the build script also publish the released artifact on github:

(see talsma-ict/context-propagation#40 for reference)

Improve the way annotations are rendered.

I was thinking of adding the @ symbol instead of the current A (for abstract class) which seems to be what gets generated at the moment.

Generics: replace T extends Object by T

Example: where types resolve to e.g. List<T extends Object> the extends Object part is redundant, as all java objects extend Object.

Rewrite for JDK9 JavaDoc tool

JDK 9 doesn't come with tools.jar anymore.

Also, to be future proof, the doclet needs to be rewritten for the new Doclet API

Built-in graphviz alternative

Since we already bundle PlantUML with the doclet, including a few extra libraries may not be so bad to reach an all-in-one solution without depending on graphviz.

A working solution is described here:

http://plantuml.com/vizjs

It may be possible to include this in the Java 9 (v2.0) doclet rewrite.

Remove ever-changing doc generation from build.

Remove the ever-changing documents from build.
These must be stabilized by removing hard versions.
The version can be automatically referenced by a maven badge (#32).

Replace .puml sources by new .svg rendering?

Recent SVG rendering engines in plantuml (at least in 1.2017.16) include the plantuml source within XML comments.
Is it then still necessary to keep the .puml files or should we allow that to be replaced by the svg altogether?

It's easy to extract the uml source from the .svg files, just match for the  regex expression.

How to add PlantUML to the classpath

Could you please extend the documentation on how to add PlantUML to the Maven config, so that SVG will be rendered automatically. I've tried:

<plugin>
    <artifactId>maven-javadoc-plugin</artifactId>

    <dependencies>
        <dependency>
            <groupId>net.sourceforge.plantuml</groupId>
            <artifactId>plantuml</artifactId>
            <version>1.2017.18</version>
        </dependency>
    </dependencies>

    <executions>
        <execution>
            <id>attach-javadocs</id>

            <goals>
                <goal>javadoc</goal>
                <goal>jar</goal>
            </goals>

            <configuration>
                <doclet>nl.talsmasoftware.umldoclet.UMLDoclet</doclet>
                <docletArtifact>
                    <groupId>nl.talsmasoftware</groupId>
                    <artifactId>umldoclet</artifactId>
                    <version>1.0.13</version>
                </docletArtifact>
                <additionalparam>
                    -umlImageFormat SVG
                </additionalparam>
            </configuration>
        </execution>
    </executions>
</plugin>

But the logoutput of umldoclet says there is no PlantUML on the classpath

Allow alternate deprecation strategies.

Currently deprecation is simply ignored.
This is probably not the best default setting.
At least I would like to see the deprecation (by strikethrough?)
Alternatively, allow a setting to remove deprecated classes / methods etc. from the UML altogether to allow for a clean model.

Links in class diagrams don't function anymore.

The link is rendered inside the class instead of making the class clickable like it used to be.
Probably the rendering of

class Name {
   [[link]]
   ...
}

was changed in a recent plantuml version. The following does seem to work though:

class Name [[link]] {
   ...
}

Add automatic license check to build

Use the maven license check to verify that a license file is added to all sources.
It can also be used to easily format all source files.

Make diagrams clickable if the renderer supports it.

This means verifying if the standard doclet is used (or an alternative javadoc location is provided todo) and providing links within the plantuml source files.

Package diagram: add relations among classes.

As usual, make this configurable with some sensible default (or maybe fully disabled initially?)
We could start with relations within the same package.

Add continuous integration to this project.

Introduce Travis CI build user
add maven wrapper
configure travis build
configure release script
sort out credentials in travis (depends on talsma-ict/enumerables#11)