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

Question

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

Ste*_*stl 4 java javadoc maven maven-javadoc-plugin

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

因此,例如,此方法的javadoc仅包含文本"一些附加信息",但不包含Stream界面中的文档.

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

Run Code Online (Sandbox Code Playgroud)

这是我对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>

Run Code Online (Sandbox Code Playgroud)

我是否会错过这种配置？我设置source和target1.8的Maven的编译器插件.因此,根据maven-javadoc-plugin的文档,应该自动检测java API.

Stack Overflow上也有类似的问题,但那里的答案似乎没有用.

Answer 1

Tun*_*aki 5

这是预期的,javadoc只复制来自源路径内的类的注释.来自方法注释继承:

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

但是,JDK的源不在源路径中,因此{@inheritDoc}不会复制它.他们需要明确地添加; 在Javadoc中常见问题有这个条目:

从J2SE继承注释 - 您的代码也可以自动从J2SE中的接口和类继承注释.您可以通过解压缩src.zip随SDK附带的文件(但不包含所有源文件)并将其路径添加到其中来完成此操作-sourcepath.在javadoc代码上运行时,它将根据需要从这些源文件加载doc注释.例如,如果代码中的类实现java.lang.Comparable,则compareTo(Object)您实现的方法将继承doc注释java.lang.Comparable.

所以,要使它工作:

找到JDK的源代码并将其解压缩到某处.
配置maven-javadoc-plugin使用sourcepath参数添加这些源.
有了上面的内容,我们还会生成JDK本身的Javadoc,这是不必要的(我们只想继承),所以我们可以subpackages用来只指定我们的包.或者,我们可以excludePackageNames用来排除JDK包.
在JDK(至少甲骨文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>

Run Code Online (Sandbox Code Playgroud)

生成Javadoc,例如with mvn javadoc:javadoc,将正确解析{@inheritDoc}.

归档时间：	9 年，3 月前
查看次数：	609 次
最近记录：	6 年，9 月前