适用于Java API核心类的maven-javadoc-plugin和InheritDoc [英] maven-javadoc-plugin and inheritDoc for Java API core classes

问题描述

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

I am writing my own Java 8 Stream implementation and want to inherit the Javadocs from the original java.util.stream.Stream interface. However I cannot get it working. The generated Javadoc does only show my documentation but not the documentation from the extended Stream interface.

因此，例如，此方法的javadoc仅包含文本一些其他信息"，而不包含Stream界面中的文档.

So for example, the javadoc of this method does only contain the text "Some additional information" but not the documentation from the Stream interface.

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

这是我对maven-javadoc-plugin的配置:

This is my configuration of the 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.

Do I miss something in this configuration? I set source and target to 1.8 in the maven-compiler-plugin. So according to the documentation of the maven-javadoc-plugin, the java API should be detected automatically.

还有一个关于堆栈溢出的类似问题，但那里的答案似乎没有帮助.

There was also a similar question on Stack Overflow but the answers there do not seem helpful.

推荐答案

可以预期，javadoc仅复制源路径中的类中的注释.从方法注释继承:

That is expected, javadoc only copies comments from classes that are inside the source path. From Method Comment Inheritance:

注意:继承方法的源文件必须位于-sourcepath选项指定的路径上，以便可以复制文档注释.该类或其包都不需要在命令行中传递.这与1.3.n版和更早的版本形成鲜明对比，后者的类必须是有文档记录的类.

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的源代码不在源路径中，因此 Javadoc常见问题解答具有以下条目:

However, the sources of your JDK aren't in the source path, so {@inheritDoc} won't copy it. They need to be added explicitely; the Javadoc FAQ has this entry:

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

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.

因此，要使其起作用:

1. 找到JDK的源并将其解压缩到某个地方.
2. 配置maven-javadoc-plugin以使用 sourcepath 参数.
3. 通过上述内容，我们还将生成JDK本身的Javadoc，这是不必要的(我们只想继承)，因此我们可以使用 excludePackageNames 来排除JDK软件包.
4. JDK(至少是Oracle JDK)还使用新的Javadoc条目，即@apiNote，@implSpec和@implNote.这些是自定义标签，需要与 参数.

1. Locate the sources of your JDK and unzip them somewhere.
2. Configure the maven-javadoc-plugin to add those sources with the sourcepath parameter.
3. With the above, we would also generate the Javadoc of the JDK itself, which is unnecessary (we only want to inherit), so we can use subpackages to specify only our packages. Alternatively, we can use excludePackageNames to exclude the JDK packages.
4. The JDK (at least Oracle JDK) also uses new Javadoc entries, namely @apiNote, @implSpec and @implNote. Those are custom tags that need to be added with the tags parameter.

这是一个示例配置，其中到JDK源的路径为/path/to/jdk/sources(您也可以使用环境变量，由配置文件设置的属性等)，并且您自己的源文件都在软件包my.package中. :

Here's a sample configuration, where the path to the JDK sources is /path/to/jdk/sources (you could also use an environment variable, a property set by profile, etc.) and your own source files are all in the package 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>

例如，使用mvn javadoc:javadoc生成Javadoc将正确解析{@inheritDoc}.

Generating the Javadoc, for example with mvn javadoc:javadoc, will correctly resolve the {@inheritDoc}.

这篇关于适用于Java API核心类的maven-javadoc-plugin和InheritDoc的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！