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

Question

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

因此，例如，此方法的 javadoc 只包含文本 "Some additional information" 而不是来自 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:

Note: The source file for an inherited method must be on the path specified by the -sourcepath option for the documentation comment to be available to copy. Neither the class nor its package needs to be passed in on the command line. This contrasts with Release 1.3.n and earlier releases, where the class had to be a documented class.

但是，您的 JDK 的来源不在源路径中，因此 {@inheritDoc} won't copy it. They need to be added explicitely; the Javadoc FAQ has this entry:

Inheriting Comments from J2SE - Your code can also automatically inherit comments from interfaces and classes in the J2SE. You can do this by unzipping the src.zip file that ships with the SDK (it does not contain all source files, however), and add its path to -sourcepath. When javadoc runs on your code, it will load the doc comments from those source files as needed. For example, if a class in your code implements java.lang.Comparable, the compareTo(Object) method you implement will inherit the doc comment from java.lang.Comparable.

因此，要让它发挥作用：

找到您的 JDK 的来源并将它们解压缩到某个地方。
配置 maven-javadoc-plugin 以使用 sourcepath 参数添加这些来源。
通过上面，我们还要生成JDK本身的Javadoc，这是不必要的（我们只想继承），所以我们可以使用subpackages to specify only our packages. Alternatively, we can use excludePackageNames来排除[=59] =] 包。
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}。

Answer 2

很棒，但从 Java 10 开始，您有更好的选择。如果您将 --override-methods=summary 传递给 Javadoc 工具，它会将所有继承的方法推送到下面的 "Methods declared in class X" 部分。这将列出继承的方法。单击方法名称会将用户带到基础 class.

中的 Javadoc 定义

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

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

maven-javadoc-plugin and inheritDoc for Java API core classes

java

javadoc

maven

maven-javadoc-plugin

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