configure javadoc links in offline mode to link to local copy

Question

How do I create javadocs that link to files in the local filesystem in offline mode?

I am building javadocs for a java package and want the links of external packages (including java.lang) to point to a local copy. This works by setting the links property like so:

<configuration>
  <links>
    <link>/usr/share/doc/default-jdk-doc/api/</link>
  </links>
</configuration>

However, the links property is ignored when working offline, even when linking to a local copy of the javadocs. My understanding is that in such case, I should be using offlineLinks but I can't make it work.

All documentation I see for offlineLinks sets url to an external URL and location to a local file. The use case seems to be creating links to external server, by using a local copy. I have tried to set both url and location to the same value but this seems to be ignored.

<offlineLinks>
  <offlineLink>
    <url>/usr/share/doc/default-jdk-doc/api/</url>
    <location>/usr/share/doc/default-jdk-doc/api/</location>
  </offlineLink>
</offlineLinks>

I have created a minimal example as a github gist which I am calling like so:

mvn --offline javadoc:javadoc

It has a single package and method that takes a String as argument. I want the javadocs to create a link to a local copy of the docs but instead I keep getting String linked to docs.oracle.com instead.

Answer 1

The javadoc program would handle the -links option properly, even if it was a local directory and there was no without internet connection. The problem is the maven javadoc plugin which ignores the links property in offline mode. The solution is to pass that option directly to the javadoc program via the additionalparam property like so:

<configuration>
  <additionalparam>-link /usr/share/doc/default-jdk-doc/api/</additionalparam>
</configuration>

This has two problems:

1. It becomes too long if linking to many different packages. In theory, one should be able to pass multiple -link options in a single additionalparam parameter.
2. The additionalparam is deprecated. However, there is no other maven property to pass javadoc options directly so hopefully they won't actually remove it.

The offlineLinks property, which would map to the command line option -linkoffline seems to really require an external URL. I am unsure if that's a requirement in the javadoc program or in the maven javadoc plugin.