首页 > 编程语言> > Java API核心类的maven-javadoc-plugin和inheritDoc

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

2019-06-08 18:51:30 作者：互联网

我正在编写自己的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...
}

这是我对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,但那里的答案似乎没有帮助.

解决方法:

这是预期的,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}不会复制它.它们需要明确地添加; 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来仅指定我们的包.或者,我们可以使用excludePackageNames来排除JDK包.
> JDK(至少Oracle JDK)也使用新的Javadoc条目,即@ apiNote,@ implSpec和@implNote.这些是需要使用tags参数添加的自定义标记.

这是一个示例配置,其中JDK源的路径是/ path / to / jdk / sources(您还可以使用环境变量,由配置文件设置的属性等),并且您自己的源文件都在我的包中.包：

<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,maven,javadoc,maven-javadoc-plugin
来源： https://codeday.me/bug/20190608/1199525.html