doclet in maven-javadoc-plugin with JDK10 - complains invalid tag "-author"?

[earcam]

Hi,

I'm seeing the following when building with Maven 3.5.4 and maven-javadoc-plugin 3.0.1 with Maven using Java 10.0.1 (on Linux Mint, dot - graphviz version 2.38.0 (20140413.2041)).

org.apache.maven.reporting.MavenReportException: 
Exit code: 1 - javadoc: warning - The old Doclet and Taglet APIs in the packages
com.sun.javadoc, com.sun.tools.doclets and their implementations
are planned to be removed in a future JDK release. These
components have been superseded by the new APIs in jdk.javadoc.doclet.
Users are strongly recommended to migrate to the new APIs.
javadoc: error - invalid flag: -author

If I comment out the doclet then the build succeeds, so while I've github-searched this repo for 'author' and can find no relevant reference, the issue appears somewhere in here.

It's not a show-stopper for Maven users - if they use toolchains for their own code and set the Java version Maven uses to <= 1.9 then all's good. But JDK's have a limited shelf life these days.

Error message above is a strong indication of Oracle aggressive approach to advancing the platform while still purporting backwards compatibility - stuff that's been relied on for a decade or more, deprecated and then broken/borken rather too quickly.

In all seriousness, this doclet running in a Maven build, is the only reason I bother to generate JavaDoc. It's UML loveliness is widely spread (e.g. https://www.javadoc.io/doc/io.earcam.wrapped/com.sun.tools.attach/1.8.0_jdk8u172-b11 or even better https://static.javadoc.io/io.earcam.wrapped/jdk.compiler/1.8.132/com/sun/tools/javac/tree/package-summary.html large monitor required 😀)

Side note; regarding issue #46 - things have got a lot easier WRT Maven releases, I'd be more than happy to help resolve that issue and this.

Thank you 👍

[dspinellis]

Thank you very much for the posting the issue with the detailed commentary. I agree that failing backward compatibility is a problem, even a smell, indicating either shoddy earlier designs or a disrespect toward developers. This year I'm sadly overcommitted, so I'd be very happy if you took on this issue and #46.

[kno10]

I see the same issue with Java 11 (and Gradle builds). It comes along with a warning that the doclet API (which IIRC never was actually "finished" but it was always planned to make this easier to extend, that just never happened...) has moved to a different package, rather than the old com.sun.javadoc. And it is not just a rename - it's moving to a design that seems to be much closer to the java language specification, whereas the old "api" was more documentation oriented.
So it may be necessary to make a new version of the doclet for Java9+.
There is a "migration guide": https://docs.oracle.com/javase/9/docs/api/jdk/javadoc/doclet/package-summary.html#migration but I had a look and it is an overwhelming amount of rewriting necessary for this. This API is more designed for compilers, I guess...

An example with the newer APIs on the document side is here: https://github.com/AdoptOpenJDK/openjdk-jdk11/blob/master/test/langtools/jdk/javadoc/tool/api/basic/taglets/UnderlineTaglet.java
but this part of the API seems to be very much oriented to document trees; tree visitors are convenient for document trees such as HTML; but supposedly much less so for accessing metadata stored via @tag annotations. In particular, a block annotation such as @tag have their contents modeled as a "list of doctree" themselves (probably because there could be inline tags there... ? Think of @tag returns {@code void}... all but elegant for this use case. I am wondering whether java annotations rather than javadoc annotations (with retention policy SOURCE?) may be the more appropriate choice then.

[dspinellis]

I originally based UMLGraph on Java's syntax to save on the effort of creating a domain-specific language for expressing the class diagrams. Then people started using UMLGraph to document and reverse-engineer existing Java code. Sadly, I have no way of knowing what use cases UMLGraph users want solved, so I guess the best approach is to wait for a direction regarding the evolution of UMLGraph to surface from the community through a pull request.

[kno10]

@dspinellis the GSoC project for Java 9+ support https://github.com/eellak/gsoc2019-UMLGraph should be finished by now.
Did anything usable come out of this, or is it still missing some key functionality?

[dspinellis]

Probably yes, but we are facing some problems with Mockito, that don't allow us to merge the changes into master.

[kno10]

Any progress on this? Java 8 is slowly slowly being replaced with Java 11.

[dspinellis]

Under GSoC last year @ekaratarakis did a log of work on the project. Waiting for him to integrate it.

[kno10]

That is why I am asking - whether his modifications will eventually become available.

[ekaratarakis]

Hello. There were some problems with Mockito that took some time. A short timetable for the final release is the following.

• A few more issues, that have to do with the javadoc tags, need to be resolved in the next couple of weeks.
• After that there will be a bit more testing of course.
• Then some final steps will follow in order to build the necessary files for the user to install and run the tool.

Thus, I would say (roughly) that by the end of this summer the new version will be available. I will keep everybody updated on the progress, of course.

[dspinellis]

@ekaratarakis very nice to read your plan! Let's integrate your work as soon as you have something that can be used. Our goal is not to release something perfect, but to release something that others can help perfect. As the mantra goes: "release early release often". Consequently, prioritize those actions that will allow you to release a version that compiles and runs.

[kno10]

@ekaratarakis @dspinellis any progress? It's been a few years since the UMLgraph doclet is broken, unfortunately.
Otherwise, I'll probably drop the tags from my javadoc.