You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Alex Herbert <al...@gmail.com> on 2022/09/23 22:14:18 UTC
[parent] Remove javadoc plugin
Commons parent configures links [1] in the maven javadoc plugin:
<links>
<link>${commons.javadoc.java.link}</link>
<link>${commons.javadoc.javaee.link}</link>
</links>
These default to standard locations for the JDK API docs and can be
configured using available properties in CP. However I do not think they
are required. The current maven javadoc plugin has a property
<detectJavaApiLink> which adds the links based on the current source.
Typically this does not affect a build as the links are added and
duplicated links would be ignored. However when building on JDK 17 the link
for Java 8 is looking for an element list for the module-based Javadoc API:
https://docs.oracle.com/javase/8/docs/api/element-list
not the classic package based Javadoc API:
https://docs.oracle.com/javase/8/docs/api/package-list
The element-list URL does not exist (modules did not exist for JDK 8) and
is redirected to the latest JDK:
https://docs.oracle.com/en/java/javase/19/
This creates a Javadoc plugin warning that the configured link is
redirected. When building the RNG project this fails the build (as any
javadoc warnings are configured to fail the build).
I could not set any configuration in the maven javadoc plugin to get around
this warning. I am building using MacOS:
Maven home: /usr/local/apache-maven-3.6.3
Java version: 17, vendor: Oracle Corporation, runtime:
/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
I have removed the links using:
<links combine.self="override">
</links>
The error then disappears and the build completes. The rendered Javadoc
still has links to all JDK objects as the <detectJavaApiLink> defaults to
true.
I believe the <links> property is to be used for any non-standard links.
There is even a <detectLinks> property to do some auto detection of
dependencies based on artifact names; this defaults to false. The JDK links
should not be required in the configuration for these standard links.
Alex
[1]
https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#links
[2]
https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#detectJavaApiLink
Re: [parent] Remove javadoc plugin
Posted by Alex Herbert <al...@gmail.com>.
On Sat, 24 Sept 2022 at 01:16, Gary Gregory <ga...@gmail.com> wrote:
> I never build releases on Java 17, only Java 8 these days. Could this be
> addressed in a profile?
>
But we test on all LTS versions. This breaks the JDK 17 build on RNG on
certain platforms.
Maven configuration is harder to remove than add when using profiles. I
think the links section is not required as it only contains standard links
added correctly by the javadoc plugin. Without it the javadoc still renders
as expected.
For example if I remove the section from CP, and then remove the duplicate
links added in the commons-lang POM:
<links>
<link>https://commons.apache.org/proper/commons-text/apidocs</
link>
<link>https://docs.oracle.com/javase/8/docs/api</link>
<link>https://docs.oracle.com/javaee/6/api</link>
</links>
When you render the javadoc for [lang] all the links to JDK objects still
work. Here the only extra link required is the one to [text] (although that
also seems unnecessary as no objects from [text] are ever imported; the
links are hard coded as anchors in the source files of the lang3.text
package).
Alex
Re: [parent] Remove javadoc plugin
Posted by Gary Gregory <ga...@gmail.com>.
I never build releases on Java 17, only Java 8 these days. Could this be
addressed in a profile?
Gary
On Fri, Sep 23, 2022, 18:14 Alex Herbert <al...@gmail.com> wrote:
> Commons parent configures links [1] in the maven javadoc plugin:
>
> <links>
>
> <link>${commons.javadoc.java.link}</link>
>
> <link>${commons.javadoc.javaee.link}</link>
>
> </links>
>
> These default to standard locations for the JDK API docs and can be
> configured using available properties in CP. However I do not think they
> are required. The current maven javadoc plugin has a property
> <detectJavaApiLink> which adds the links based on the current source.
>
> Typically this does not affect a build as the links are added and
> duplicated links would be ignored. However when building on JDK 17 the link
> for Java 8 is looking for an element list for the module-based Javadoc API:
>
> https://docs.oracle.com/javase/8/docs/api/element-list
>
> not the classic package based Javadoc API:
>
> https://docs.oracle.com/javase/8/docs/api/package-list
>
> The element-list URL does not exist (modules did not exist for JDK 8) and
> is redirected to the latest JDK:
>
> https://docs.oracle.com/en/java/javase/19/
>
> This creates a Javadoc plugin warning that the configured link is
> redirected. When building the RNG project this fails the build (as any
> javadoc warnings are configured to fail the build).
>
> I could not set any configuration in the maven javadoc plugin to get around
> this warning. I am building using MacOS:
>
> Maven home: /usr/local/apache-maven-3.6.3
>
> Java version: 17, vendor: Oracle Corporation, runtime:
> /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
>
> I have removed the links using:
>
> <links combine.self="override">
>
> </links>
>
> The error then disappears and the build completes. The rendered Javadoc
> still has links to all JDK objects as the <detectJavaApiLink> defaults to
> true.
>
> I believe the <links> property is to be used for any non-standard links.
> There is even a <detectLinks> property to do some auto detection of
> dependencies based on artifact names; this defaults to false. The JDK links
> should not be required in the configuration for these standard links.
>
> Alex
>
>
> [1]
>
> https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#links
> [2]
>
> https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#detectJavaApiLink
>