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!

The Javadoc Plugin uses the Javadoc tool to generate javadocs for your project. Just download the javadoc of your dependencies: mvn dependency:resolve -Dclassifier=javadoc Have look here: baeldung maven-download-sources-javadoc — Dirk Deyne
– Dirk Deyne, Commented Nov 21, 2020 at 10:12
@DirkDeyne I wonder if downloading source and javadoc files via maven-dependency-plugin has anything to do with maven-javadoc-plugin. It seems that maven-dependency-plugin merely pulls some files off of a remote repository. And those files can then be used by an IDE to show up pop-up docs or to let you view source files of your dependencies. — Janez Kuhar
– Janez Kuhar, Commented Nov 22, 2020 at 11:53
IIUC only transitive required modules end up as indirect export. Don't get confused by the word transitive: for Maven it means dependencies of direct dependencies, whereas for Java modules it means implied readability, so users of your module don't need to add a read on these in their descriptor — Robert Scholte
– Robert Scholte, Commented Nov 22, 2020 at 16:50
@RobertScholte It appears to be so, my mistake. But if I define my module dependency as requires transitive com.github.glusk.caesar;, it won't show up in my module doc under: "Modules" --> "Requires" and the packages it exports don't get listed under "Packages" --> "Indirect Exports". — Janez Kuhar
– Janez Kuhar, Commented Nov 22, 2020 at 17:59

Dirk Deyne · Accepted Answer · 2020-11-23 20:11:18Z

2

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>

edited Nov 23, 2020 at 20:11

answered Nov 22, 2020 at 14:04

Dirk Deyne

6,9961 gold badge22 silver badges36 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Philippe Gioseffi Over a year ago

What if you have maven modules and needs to reference a class from the other module?

Collectives™ on Stack Overflow

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

1 Answer 1

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related