我正在编写自己的 Java 8 Stream 实现，并希望从原始 java.util.stream.Stream 接口(interface)继承 Javadoc。但是我无法让它工作。生成的 Javadoc 只显示我的文档，而不显示来自扩展 Stream 接口(interface)的文档。
例如，此方法的 javadoc 仅包含文本“一些附加信息”，而不包含来自 Stream 接口(interface)的文档。
/**
* {@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。
还有一个 similar question在 Stack Overflow 上，但那里的答案似乎没有帮助。
最佳答案
这是预料之中的，javadoc 只从源路径内的类复制注释。来自 Method Comment Inheritance :
Note: The source file for an inherited method must be on the path specified by the
-sourcepathoption 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}不会复制它。需要明确地添加它们； 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.zipfile that ships with the SDK (it does not contain all source files, however), and add its path to-sourcepath. Whenjavadocruns on your code, it will load the doc comments from those source files as needed. For example, if a class in your code implementsjava.lang.Comparable, thecompareTo(Object)method you implement will inherit the doc comment fromjava.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}。
关于java - Java API 核心类的 maven-javadoc-plugin 和 inheritDoc，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/38707030/