Question

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

因此，例如，此方法的javadoc仅包含文本＆＃34;一些附加信息＆＃34;但不是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，但那里的答案似乎没有帮助。

Answer 1

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

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

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

从J2SE继承注释 - 您的代码也可以自动继承J2SE中接口和类的注释。您可以通过解压缩随SDK附带的src.zip文件（但不包含所有源文件）来完成此操作，并将其路径添加到-sourcepath。当javadoc在您的代码上运行时，它会根据需要从这些源文件中加载文档注释。例如，如果代码中的某个类实现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（您还可以使用环境变量，由配置文件设置的属性等），并且您自己的源文件都在包中{ {1}}：

my.package

生成Javadoc，例如使用<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>，将正确解析mvn javadoc:javadoc。

Answer 2

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

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

用于Java API核心类的maven-javadoc-plugin和inheritDoc

2 个答案: