Java API 核心类的 maven-javadoc-plugin 和 inheritDoc答案

【问题标题】：maven-javadoc-plugin and inheritDoc for Java API core classesJava API 核心类的 maven-javadoc-plugin 和 inheritDoc
【发布时间】：2016-12-07 00:24:21
【问题描述】：

我正在编写自己的 Java 8 Stream 实现，并希望从原始 java.util.stream.Stream 接口继承 Javadocs。但是我无法让它工作。生成的 Javadoc 仅显示我的文档，而不显示来自扩展 Stream 接口的文档。

因此，例如，此方法的 javadoc 仅包含文本“一些附加信息”，但不包含来自 Stream 接口的文档。

/**
 * {@inheritDoc}
 * Some additional information.
 */
@Override
public Stream<T> filter(Predicate<? super T> predicate) {
  // ... my stream implementation...
}

这是我对 maven-javadoc-plugin 的配置：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.10.1</version>
  <configuration>
    <links>
      <link>http://docs.oracle.com/javase/8/docs/api/</link>
    </links>
  </configuration>
</plugin>

我是否错过了此配置中的某些内容？我在 maven-compiler-plugin 中将 source 和 target 设置为 1.8。所以根据maven-javadoc-plugin的文档，应该会自动检测到java API。

Stack Overflow 上还有一个 similar question，但那里的答案似乎没有帮助。

【问题讨论】：

标签： java maven javadoc maven-javadoc-plugin

【解决方案1】：

这是预期的，javadoc 仅从源路径内的类复制 cmets。来自Method Comment Inheritance：

注意： 继承方法的源文件必须位于-sourcepath 选项指定的路径上，文档注释才能复制。类和它的包都不需要在命令行中传入。这与版本 1.3.n 和更早版本形成对比，其中类必须是文档类。

但是，您的 JDK 的源不在源路径中，因此{@inheritDoc} 不会复制它。它们需要明确添加； Javadoc FAQ has this entry:

从 J2SE 继承注释 - 您的代码还可以自动从 J2SE 中的接口和类继承 cmets。为此，您可以解压缩 SDK 附带的 src.zip 文件（但它不包含所有源文件），并将其路径添加到 -sourcepath。当javadoc 在您的代码上运行时，它将根据需要从这些源文件中加载 doc cmets。例如，如果您的代码中的某个类实现了java.lang.Comparable，那么您实现的compareTo(Object) 方法将继承java.lang.Comparable 的文档注释。

所以，让它发挥作用：

找到 JDK 的源并将其解压缩到某个位置。
配置maven-javadoc-plugin 以使用sourcepath 参数添加这些源。
通过以上，我们还会生成JDK本身的Javadoc，这是不必要的（我们只想继承），所以我们可以使用subpackages只指定我们的包。或者，我们可以使用excludePackageNames 排除JDK 包。
JDK（至少是 Oracle JDK）也使用新的 Javadoc 条目，即 @apiNote、@implSpec 和 @implNote。这些是需要使用tags 参数添加的自定义标签。

这是一个示例配置，其中 JDK 源的路径是 /path/to/jdk/sources（您也可以使用环境变量、配置文件设置的属性等）并且您自己的源文件都在包中 my.package ：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.1</version>
    <configuration>
        <sourcepath>/path/to/jdk/sources:${basedir}/src/main/java</sourcepath>
        <subpackages>my.package</subpackages>
        <tags>
            <tag>
                <name>apiNote</name>
                <placement>a</placement>
                <head>API Note:</head>
            </tag>
            <tag>
                <name>implSpec</name>
                <placement>a</placement>
                <head>Implementation Requirements:</head>
            </tag>
            <tag>
                <name>implNote</name>
                <placement>a</placement>
                <head>Implementation Note:</head>
            </tag>
        </tags>
    </configuration>
</plugin>

生成 Javadoc，例如使用 mvn javadoc:javadoc，将正确解析 {@inheritDoc}。

【讨论】：

谢谢，成功了。通过将system 范围依赖声明为${java.home}/../src.zip，我还设法在maven 构建期间直接提取src.zip。有了这个依赖，我可以使用 maven-dependency-plugin 的 unpack-dependencies 目标，包括我需要的包。对于java.util 包（我不需要更多），这将只需要几秒钟。

【解决方案2】：

Tunaki's answer 很棒，但从 Java 10 开始，您有一个更好的选择。如果您将--override-methods=summary 传递给Javadoc 工具，它会将所有继承的方法下推到下面的“在类X 中声明的方法”部分。这将列出继承的方法。单击方法名称会将用户带到基类中的 Javadoc 定义。

有关背景信息，请参阅https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8187386。

【讨论】：