talsma-ict / umldoclet Goto Github PK

I was thinking to enable it by default too.

Think about the tags to use.
The tags should allow for great flexibility while keeping the number of tags to a minimum.
This is because all other doclets need to ignore our tags to produce valid standard documenation.

Multiple improvements possible:

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

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.

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.

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.

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.

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

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

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.

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.

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.

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>

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

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

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

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

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

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 <!--.*(@startuml.*@enduml).*--> regex expression.

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.

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.

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

Think about pegdown doclet that interprets Markdown style JavaDoc and various similar doclets.
I think UML generation combines nicely with any kind of 'documentation style' doclet.

When invalid javadoc is encountered by the maven build, the build fails with an error, but the error that caused the issue is not printed when the uml doclet is used. Without the uml doclet a clear error is printed about the invalid javadoc.

Maven version: 3.3.3
JDK version: 1.8.0_74

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]] {
   ...
}

There are some outdated test dependencies:

http://mvnrepository.com/artifact/nl.talsmasoftware/umldoclet/0.1.4

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

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.

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.

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.

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

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

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

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

additionalparam becomes additionalOptions since maven-javadoc-plugin version 3.0.0

Badges for:

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

As always: make it configurable.

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

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

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

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.

At least document how to use with:

• gradle
• commandline

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

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

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

• github release API
• example how to call from cli
• Create and add pre-built artifacts to a GitHub release from CI server using the GitHub releases API

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

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

Requirements for this API:

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

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.

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.