java - 如何使用 Maven Javadoc 插件正确链接到模块化依赖项？

Question

在我的 project ，我试图在由 javadoc 生成的文档文件中包含指向模块化 Java 库(Caesar)的链接。工具。运行:

mvn clean install

构建没有外部库链接的文档。
我的配置:

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>

系统信息:

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"

更新 #1
将 Maven 依赖插件添加到 pom.xml 后(如 article 中的建议；下载项目依赖项的源代码和 javadocs):

<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>

并运行:

mvn clean install

生成的 HTML 文档中仍然缺少链接。但是，Maven 会输出这些额外的构建日志行:

[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]

更新 #2
添加:

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

到 <configuration/> maven-javadoc-plugin 的标签添加类和包链接，但未能包含模块链接。
我期待看到以下部分:

包 --> 间接导出

模块 --> 需要

在 project/target/apidocs/foo.bar.project/module-summary.html , 很像 here ，如果我定义我的 module-info.java作为:

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

更新#3
以下 Maven Javadoc 插件 <configuration/>堵塞:

<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>

构建 project带有 Caesar javadocs 链接的文档托管在 https://javadoc.io .标记 --show-module-contents all包括所有模块引用，包括 java.base ，这不是我真正想要的，因为该模块中有太多的包，它会使文档困惑。
另一方面，以下配置:

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

从 Maven Central 获取依赖文档并构建独立文档。唯一的外部链接是指向 Java SE API 的链接。但它并不完全有效: mvn clean install引发以下警告:

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

和模块的包文档 com.github.glusk.caesar不包含在生成的文档中。但是， project/target/apidocs/foo.bar.project/module-summary.html看起来和我想要的一模一样!

Answer 1

我假设您使用 @link在您的 javadoc 中引用。
就像是:

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

为了使 {@link ImmutableMessageDigest} 在生成的 javadoc 中转换为实际的 HTML 链接，您需要添加对实际外部 javadoc 的引用。
这可以通过配置 link 来实现在 maven-javadoc-plugin .
在您的情况下，这将是 <link>https://javadoc.io/doc/com.github.glusk/caesar/0.4.0</link>包括 Indirect Exports在 module-summary.html 中，您需要添加(附加)选项 --show-module-contents all导致:

<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>