How to properly link to a modularized dependency using the Maven Javadoc Plugin?

Question

In my project, I'm trying to include links to a modularized Java library (Caesar) in the documentation files generated by the javadoc tool. Running:

mvn clean install

builds the docs without links to the external library.

My configuration:

project
|-- pom.xml
`-- src
    `-- main
        `-- java
            |-- foo.bar.project
            |   `-- foo
            |       `-- bar
            |           `-- project
            |               `-- Foo.java
            `-- module-info.java

Foo.java:

package foo.bar.project;

import com.github.glusk.caesar.Bytes;

public class Foo {
    public static Bytes bytes;
}

module-info.java:

module foo.bar.project {
    requires com.github.glusk.caesar;
}

pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>foo.bar</groupId>
  <artifactId>project</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>11</maven.compiler.release>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.github.glusk</groupId>
      <artifactId>caesar</artifactId>
      <version>0.4.0</version>
    </dependency>
  </dependencies>

  <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.8.1</version>
          <executions>
            <execution>
                <goals>
                    <goal>compile</goal>
                </goals>
                <id>compile</id>
            </execution>
          </executions>
        </plugin>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-javadoc-plugin</artifactId>
          <version>3.2.0</version>
          <configuration>
            <sourcepath>${project.build.sourceDirectory}</sourcepath>
          </configuration>
          <executions>
            <execution>
              <id>attach-javadocs</id>
              <goals>
                <goal>jar</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
  </build>
</project>

---

System info:

Picked up JAVA_TOOL_OPTIONS: -Dfile.encoding=UTF8
Apache Maven 3.6.0 (97c98ec64a1fdfee7767ce5ffb20918da4f719f3; 2018-10-24T20:41:47+02:00)
Maven home: C:\Tools\apache-maven-3.6.0
Java version: 11.0.8, vendor: Oracle Corporation, runtime: C:\Program Files\Java\jdk-11.0.8
Default locale: sl_SI, platform encoding: UTF8
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"

---

UPDATE #1

After adding the Maven Dependency Plugin to pom.xml (like suggested in this article; to download sources and javadocs of project dependencies):

<project>
  <!-- ... -->
  <build>
      <plugins>
          <!-- ... -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-dependency-plugin</artifactId>
          <version>3.1.2</version>
          <executions>
            <execution>
              <goals>
                <goal>sources</goal>
                <goal>resolve</goal>
              </goals>
              <configuration>
                <classifier>javadoc</classifier>
              </configuration>
            </execution>
          </executions>
        </plugin>
      </plugins>
  </build>
</project>

and running:

mvn clean install

the links are still missing in the generated HTML docs. However, Maven outputs these additional build log lines:

[INFO] --- maven-dependency-plugin:3.1.2:sources (default) @ project ---
[INFO] 
[INFO] The following files have been resolved:
[INFO]    com.github.glusk:caesar:jar:javadoc:0.4.0 -- module caesar (auto)
[INFO]
[INFO] The following files have NOT been resolved:
[INFO]    com.github.glusk:caesar:jar:0.4.0:compile -- module com.github.glusk.caesar
[INFO]
[INFO]
[INFO] --- maven-dependency-plugin:3.1.2:resolve (default) @ project ---
[INFO] 
[INFO] The following files have been resolved:
[INFO]    com.github.glusk:caesar:jar:javadoc:0.4.0 -- module caesar (auto)
[INFO] 
[INFO] The following files have NOT been resolved:
[INFO]    com.github.glusk:caesar:jar:0.4.0:compile -- module com.github.glusk.caesar
[INFO]
[INFO]

---

UPDATE #2

Adding:

<links>
  <link>https://javadoc.io/doc/com.github.glusk/caesar/0.4.0</link>
</links>

to the <configuration/> tag of maven-javadoc-plugin adds class and package links but fails to include module links.

I'm expecting to see sections:

• Packages --> Indirect Exports
• Modules --> Requires

in project/target/apidocs/foo.bar.project/module-summary.html, much like here, if I define my module-info.java as:

module foo.bar.project {
    requires transitive com.github.glusk.caesar;
}

---

UPDATE #3

The following Maven Javadoc Plugin <configuration/> block:

<configuration>
  <sourcepath>${project.build.sourceDirectory}</sourcepath>
  <links>
    <link>https://javadoc.io/doc/com.github.glusk/caesar/0.4.0</link>
  </links>
  <additionalOptions>
    <option>--show-module-contents all</option>
  </additionalOptions>
</configuration>

builds project docs with links to Caesar javadocs hosted at https://javadoc.io. Flag --show-module-contents all includes all module references, including java.base, which is not really what I want, because there are too many packages in that module and it clutters up the documentation.

On the other hand, the following configuration:

<configuration>
  <sourcepath>${project.build.sourceDirectory}</sourcepath>
  <additionalOptions>
    <option>--module foo.bar.project</option>
    <option>--expand-requires transitive</option>
  </additionalOptions>
</configuration>

fetches the dependency documentation from Maven Central and builds stand-alone docs. The only external links are those to the Java SE API. But it doesn't quite work: mvn clean install throws the following warnings:

[WARNING] Javadoc Warnings
[WARNING] javadoc: warning - module caesar not found.
[WARNING] javadoc: warning - module caesar not found.

and package documentation of module com.github.glusk.caesar is not included in the generated docs. However, project/target/apidocs/foo.bar.project/module-summary.html looks exactly like I want!

Answer 1

I assume you use a @link reference in your javadoc.

Something like:

 /**
  * have a look here: {@link ImmutableMessageDigest}
  * @see <a href="https://github.com/Glusk/caesar">Glusk Caesar</a>
  */
 public void bar(){
   // your code
 }

In order to make {@link ImmutableMessageDigest} to be converted to an actual HTML link in your generated javadoc, you need to add a reference to the actual external javadoc.

This can be achieved by configuring a link in the maven-javadoc-plugin.

In your case, this would be <link>https://javadoc.io/doc/com.github.glusk/caesar/0.4.0</link>

To include Indirect Exports in the module-summary.html you need to add the (additional) option --show-module-contents all

resulting in:

<plugin>
   <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-javadoc-plugin</artifactId>
       <version>3.2.0</version>
       <configuration>
          <sourcepath>${project.build.sourceDirectory}</sourcepath>
          <!-- include this part -->
          <links>
             <link>https://javadoc.io/doc/com.github.glusk/caesar/0.4.0</link>
          </links>
          <additionalOptions>
             <option>--show-module-contents all</option>
          </additionalOptions>
       </configuration>
       <executions>
         <execution>
            <id>attach-javadocs</id>
            <goals>
               <goal>jar</goal>
            </goals>
         </execution>
      </executions>
   </plugin>