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

Question

在我的 .NET 中project，我试图在该工具生成的文档文件中包含指向模块化 Java 库 ( Caesar ) 的链接javadoc。跑步：

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：

package foo.bar.project;

import com.github.glusk.caesar.Bytes;

public class Foo {
    public static Bytes bytes;
}

---

系统信息：

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

---

更新 #1

将 Maven 依赖插件添加到pom.xml（如本文建议的那样；下载项目依赖的源代码和javadoc）后：

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

并运行：

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

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

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"

---

更新 #2

添加：

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

添加类和包链接但未能包含模块链接的<configuration/>标记maven-javadoc-plugin。

我期待看到以下部分：

• 包-->间接导出
• 模块-->需要

in project/target/apidocs/foo.bar.project/module-summary.html，很像这里，如果我将我定义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与文档链接到托管凯撒的javadoc https://javadoc.io。Flag--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抛出以下警告：

mvn clean install

并且模块的包文档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>