6

我正在编写自己的 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 中将sourceand设置target为 1.8。所以根据maven-javadoc-plugin的文档，应该会自动检测到 java API。

Stack Overflow 上也有类似的问题，但那里的答案似乎没有帮助。

4

2 回答 2

8

这是预期的，javadoc只复制源路径内的类的注释。从方法注释继承：

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

但是，您的 JDK 的源不在源路径中，因此{@inheritDoc}不会复制它。它们需要明确添加；Javadoc FAQ 有这个条目：

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

因此，要使其工作：

  1. 找到 JDK 的源并将它们解压缩到某个地方。
  2. 配置maven-javadoc-plugin以使用参数添加这些源sourcepath。
  3. 有了上面，我们还会生成JDK本身的Javadoc，这是不必要的（我们只想继承），所以我们可以subpackages只指定我们的包。或者，我们可以使用excludePackageNames排除 JDK 包。
  4. 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}.

于 2016-08-01T21:25:28.357 回答
1

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

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

于 2019-01-31T19:43:27.620 回答