RFC: Switching from maven-javadoc-plugin to xmvn-javadoc

[Fabio Valentini]

Good morning!

I've been investigating build failures with java-11-openjdk as
default, and a lot of those failures are attributable to issues with
javadoc generation, in particular with maven-javadoc-plugin.

It looks like maven-javadoc-plugin cannot do dependency resolution
correctly when run on java 11, and hence generating docs fails with
"package foo does not exist" and / or "unresolved symbol bar" errors,
for example:

https://copr.fedorainfracloud.org/coprs/g/java-maint-sig/java-11-default/...

I tried setting `-Xdoclint:none` when generating javadocs, but this
had no effect on the error.

However, I found an easy solution, which was to switch from using
maven-javadoc-plugin to xmvn-javadoc for generating the docs (by
flipping the existing bcond switch in javapackages-tools). From
previous experiments with this option, it only caused minor problems
with 1-2 packages.

With xmvn-javadoc, the number of packages that fails to build on java
11 was reduced drastically - from ~every package that has dependencies
declared in pom.xml to only those that actually have build issues with
java 11 (so, from about ~1000 failing packages to ~250).

Of those remaining ~250 packages, ~125 can be fixed by overriding java
compiler source / target values to 1.8, since they use target java <
1.6 in their build systems, which is no longer supported by javac 11.
I collected those "EasyFix" packages in this ticket:

https://pagure.io/java-maint-sig/issue/1

The other half of build failures are mostly build issues that are
unrelated to the java 11 switch, and only a handful of packages looks
like it actually required code changes (yes, I looked at the build
logs for *all* the failed builds).

I've also set up a COPR for all packages that require java, with
java-1.8.0-openjdk, java-11-openjdk, and javapackages-tools with the
proposed changes + the switch to xmvn-javadoc:

https://copr.fedorainfracloud.org/coprs/g/java-maint-sig/java-11-default/

It's set up to automatically run builds in the event commits are
pushed to dist-git or Pull Requests are filed for any of the packages
the COPR contains. So, for any changes to a package, it will
automatically get built against java 11 in the COPR, as well.

TL;DR: I propose we switch to xmvn-javadoc, since it fixes most of the
build issues I see with OpenJDK 11 by default.

Alternatively: If somebody can figure out how to fix generation of
javadocs with maven-javadoc-plugin, that would be great, as that would
be a smaller change than switching the javadoc generator entirely.

What do you think?

Fabio

[Mikolaj Izdebski]

On Mon, May 25, 2020 at 11:00 AM Fabio Valentini <decathorpe(a)gmail.com&gt; wrote:
>  TL;DR: I propose we switch to xmvn-javadoc, since it fixes most of
> the
>  build issues I see with OpenJDK 11 by default. 
I'm in favor of using XMvn Javadoc MOJO instead of Maven Javadoc
Plugin, but for different reasons.

Documentation generated with Maven Javadoc Plugin is different for
different upstream projects - layout may be different, different CSS
themes, doclets (eg. some projects generate and include UML diagrams
etc.) while documentation generated with XMvn Javadoc MOJO looks the
same for every package.

Quote from XMvn release notes:

      XMvn 3.0.0 added new MOJO, which can be used to generate API
      documentation (javadocs) as alternative to Maven Javadoc Plugin.
      Goal <<<xmvn-mojo:javadoc>>> works in similar way to
      <<<javadoc:aggregate>>>, but it has some advantages over it.
      XMvn javadoc makes javadocs more consistent between packages -
      it unifies javadoc options, doclet used, CSS styles, and so on.
      It opens possibilities for better integration with distributions
      in the future, like for example distro-specific themes, links or
      dependencies between javadoc packages.  It also has much fewer
      dependencies, which means smaller builroots and faster builds.

Using Maven Javadoc MOJO keeps API docs closer to upstream while XMvn
Javadoc MOJO unifies API docs across all packages in distribution
(that are built with Maven), but makes them look different from
corresponding upstream API docs.

--
Mikolaj Izdebski

[Mat Booth]

On Mon, 25 May 2020 at 09:59, Fabio Valentini <decathorpe(a)gmail.com&gt; wrote:

>  Good morning!
>
>  I've been investigating build failures with java-11-openjdk as
>  default, and a lot of those failures are attributable to issues with
>  javadoc generation, in particular with maven-javadoc-plugin.
>
>  It looks like maven-javadoc-plugin cannot do dependency resolution
>  correctly when run on java 11, and hence generating docs fails with
>  "package foo does not exist" and / or "unresolved symbol bar"
> errors,
>  for example:
>
>
>  https://copr.fedorainfracloud.org/coprs/g/java-maint-sig/java-11-default/...
>
>  I tried setting `-Xdoclint:none` when generating javadocs, but this
>  had no effect on the error.
>
>  However, I found an easy solution, which was to switch from using
>  maven-javadoc-plugin to xmvn-javadoc for generating the docs (by
>  flipping the existing bcond switch in javapackages-tools). From
>  previous experiments with this option, it only caused minor problems
>  with 1-2 packages.
>
>  With xmvn-javadoc, the number of packages that fails to build on java
>  11 was reduced drastically - from ~every package that has dependencies
>  declared in pom.xml to only those that actually have build issues with
>  java 11 (so, from about ~1000 failing packages to ~250).
>
>  Of those remaining ~250 packages, ~125 can be fixed by overriding java
>  compiler source / target values to 1.8, since they use target java <
>  1.6 in their build systems, which is no longer supported by javac 11.
>  I collected those "EasyFix" packages in this ticket:
>
>  https://pagure.io/java-maint-sig/issue/1
>
>  The other half of build failures are mostly build issues that are
>  unrelated to the java 11 switch, and only a handful of packages looks
>  like it actually required code changes (yes, I looked at the build
>  logs for *all* the failed builds).
>
>  I've also set up a COPR for all packages that require java, with
>  java-1.8.0-openjdk, java-11-openjdk, and javapackages-tools with the
>  proposed changes + the switch to xmvn-javadoc:
>
>  https://copr.fedorainfracloud.org/coprs/g/java-maint-sig/java-11-default/
>
>  It's set up to automatically run builds in the event commits are
>  pushed to dist-git or Pull Requests are filed for any of the packages
>  the COPR contains. So, for any changes to a package, it will
>  automatically get built against java 11 in the COPR, as well.
>
>  TL;DR: I propose we switch to xmvn-javadoc, since it fixes most of the
>  build issues I see with OpenJDK 11 by default.
>
>  Alternatively: If somebody can figure out how to fix generation of
>  javadocs with maven-javadoc-plugin, that would be great, as that would
>  be a smaller change than switching the javadoc generator entirely.
>
>  What do you think?
>
>  Fabio 


I take lack of dissent as silent assent. ;-) Will you be making this change?

-- 
Mat Booth
http://fedoraproject.org/get-fedora

[Aleksandar Kurtakov]

On Thu, Jun 25, 2020 at 3:17 PM Mat Booth <fedora(a)matbooth.co.uk&gt; wrote:

>  On Mon, 25 May 2020 at 09:59, Fabio Valentini <decathorpe(a)gmail.com&gt;
>  wrote:
>
> > Good morning!
> >
> > I've been investigating build failures with java-11-openjdk as
> > default, and a lot of those failures are attributable to issues with
> > javadoc generation, in particular with maven-javadoc-plugin.
> >
> > It looks like maven-javadoc-plugin cannot do dependency resolution
> > correctly when run on java 11, and hence generating docs fails with
> > "package foo does not exist" and / or "unresolved symbol bar"
> errors,
> > for example:
> >
> >
> >
> https://copr.fedorainfracloud.org/coprs/g/java-maint-sig/java-11-default/...
> >
> > I tried setting `-Xdoclint:none` when generating javadocs, but this
> > had no effect on the error.
> >
> > However, I found an easy solution, which was to switch from using
> > maven-javadoc-plugin to xmvn-javadoc for generating the docs (by
> > flipping the existing bcond switch in javapackages-tools). From
> > previous experiments with this option, it only caused minor problems
> > with 1-2 packages.
> >
> > With xmvn-javadoc, the number of packages that fails to build on java
> > 11 was reduced drastically - from ~every package that has dependencies
> > declared in pom.xml to only those that actually have build issues with
> > java 11 (so, from about ~1000 failing packages to ~250).
> >
> > Of those remaining ~250 packages, ~125 can be fixed by overriding java
> > compiler source / target values to 1.8, since they use target java <
> > 1.6 in their build systems, which is no longer supported by javac 11.
> > I collected those "EasyFix" packages in this ticket:
> >
> > https://pagure.io/java-maint-sig/issue/1
> >
> > The other half of build failures are mostly build issues that are
> > unrelated to the java 11 switch, and only a handful of packages looks
> > like it actually required code changes (yes, I looked at the build
> > logs for *all* the failed builds).
> >
> > I've also set up a COPR for all packages that require java, with
> > java-1.8.0-openjdk, java-11-openjdk, and javapackages-tools with the
> > proposed changes + the switch to xmvn-javadoc:
> >
> > https://copr.fedorainfracloud.org/coprs/g/java-maint-sig/java-11-default/
> >
> > It's set up to automatically run builds in the event commits are
> > pushed to dist-git or Pull Requests are filed for any of the packages
> > the COPR contains. So, for any changes to a package, it will
> > automatically get built against java 11 in the COPR, as well.
> >
> > TL;DR: I propose we switch to xmvn-javadoc, since it fixes most of the
> > build issues I see with OpenJDK 11 by default.
> >
> > Alternatively: If somebody can figure out how to fix generation of
> > javadocs with maven-javadoc-plugin, that would be great, as that would
> > be a smaller change than switching the javadoc generator entirely.
> >
> > What do you think?
> >
> > Fabio
>
>
>
>  I take lack of dissent as silent assent. ;-) Will you be making this
>  change?
>  
If we need any kind of voting. Here is my +1 too.

>  --
>  Mat Booth
>  http://fedoraproject.org/get-fedora
>  _______________________________________________
>  java-devel mailing list -- java-devel(a)lists.fedoraproject.org
>  To unsubscribe send an email to java-devel-leave(a)lists.fedoraproject.org
>  Fedora Code of Conduct:
>  https://docs.fedoraproject.org/en-US/project/code-of-conduct/
>  List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
>  List Archives:
>  https://lists.fedoraproject.org/archives/list/[e-mail]...
>  

-- 
Alexander Kurtakov
Red Hat Eclipse Team