如何使javadoc继承适用于外部API？ （与Maven2） [英] How do I make javadoc inheritance work for external APIs? (with Maven2)

问题描述

当类重写具体方法或实现和抽象方法时，除非明确覆盖，否则Javadoc会自动继承。

When a class overrides a concrete method or implements and abstract method, the Javadoc is automatically inherited unless explicitly overwritten.

或者，至少该工具尝试执行此操作。它似乎不适用于链接的外部API。例如，当我在我的代码中实现 java.util.Map 或JRE中的其他内容时，javadocs不会从JRE javadocs / apidocs继承/复制。

Or, at least the tool tries to do this. It seems it does not work for linked external APIs. For instance, when I in my code implement java.util.Map, or something else from the JRE, the javadocs are not inherited/copied from the JRE javadocs/apidocs.

在我的特定情况下，我试图在Maven2 Javadoc插件中配置它，但是当我直接运行javadoc CLI工具时它是一样的。

In my specific case, I am trying to configure this in the Maven2 Javadoc plugin, but it is the same when I run the javadoc CLI tool directly.

我的Maven2 Javadoc插件配置目前如下所示：

My Maven2 Javadoc plugin configuration currently looks like this:

<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.7</version>
      <configuration>
        <stylesheet>maven</stylesheet>
        <links>
          <link>http://download.oracle.com/javase/6/docs/api</link>
        </links>
      </configuration>
    </plugin>
  </plugins>
</reporting>

有关如何使其工作的任何指示？

Any pointers on how to make this work?

推荐答案

正如@Stephen所提到的，继承方法的源文件必须可用，并且必须位于 -sourcepath 。这在Javadoc工具文档中有解释：

As @Stephen mentioned, the source file for the inherited method must be available and must be on the path specified by -sourcepath. This is explained in the Javadoc tool documentation:

自动复制方法注释

Javadoc工具有在两种情况下
类和接口下的
类和接口中
复制或继承方法注释的能力。
构造函数，字段和嵌套的
类不会继承文档注释。

Automatic Copying of Method Comments

The Javadoc tool has the ability to copy or "inherit" method comments in classes and interfaces under the following two circumstances. Constructors, fields and nested classes do not inherit doc comments.

• 自动继承评论以填写缺失的文本 - 当主
  描述，或 @return ，
  @param 或 @throws 标记从方法注释中缺少
  ，Javadoc
  工具从相应的主要
  描述或标记注释中复制
  方法它覆盖或实现（如果
  any），根据下面的算法
  。

• Automatically inherit comment to fill in missing text - When a main description, or @return, @param or @throws tag is missing from a method comment, the Javadoc tool copies the corresponding main description or tag comment from the method it overrides or implements (if any), according to the algorithm below.

更具体地说，当一个<$缺少c $ c> @param 特定
参数的标记，然后从继承$ b的
方法复制该参数的注释
$ b层次结构。当缺少
特定异常的 @throws 标记时，
@throws 标记仅在声明
异常时复制。

More specifically, when a @param tag for a particular parameter is missing, then the comment for that parameter is copied from the method further up the inheritance hierarchy. When a @throws tag for a particular exception is missing, the @throws tag is copied only if that exception is declared.

此行为与版本1.3及更早版本形成对比，其中
存在任何主要描述或
标记会阻止
的所有评论被继承。

This behavior contrasts with version 1.3 and earlier, where the presence of any main description or tag would prevent all comments from being inherited.

使用显式继承评论{@ inheritDoc } tag - 插入
内联标记方法主要描述中的/javadoc.html#%7B@inheritDoc%7D\"rel =noreferrer> {@ inheritDoc} 或 @return ，
@param 或 @throws 标记注释 -
相应的继承主
描述或标记注释被复制
到该点。

Explicitly inherit comment with {@inheritDoc} tag - Insert the inline tag {@inheritDoc} in a method main description or @return, @param or @throws tag comment -- the corresponding inherited main description or tag comment is copied into that spot.

继承的
方法的源文件只需要在
指定的路径上 -sourcepath
，文档评论实际上是
可供复制。类
及其包都不需要在命令行中以
传递。这与
和1.3.x及早期版本形成对比，其中
该类必须是记录
class

所以你必须使用 < sourcepath> javadoc插件的可选配置参数（默认情况下包含项目的源）。

So you'd have to use the <sourcepath> optional configuration parameter of the javadoc plugin (which contains by default the sources of the project).

顺便说一下，< links /> 是其他的，< links /> 用于向外部项目添加交叉引用链接。实际上，它们不应该用于JDK。来自配置链接：

By the way, <links/> are something else, <links/> are used to add cross reference links to external projects. And actually, they shouldn't be used for the JDK. From Configuring links:

从2.6开始，将添加一个Javadoc API链接，具体取决于项目使用的JDK版本。从的值中检测Javadoc API的版本< source /> 参数=noreferrer> org.apache.maven.plugins：maven-compiler-plugin （在 $ {project.build中定义。 plugins} 或在 $ {project.build.pluginManagement} ）中，或通过Javadoc Tool可执行文件计算。如果您想跳过此链接，则需要配置 < detectJavaApiLink /> 到 false 。

Since 2.6, a Javadoc API link, depending the JDK version used by your project, will be added. The version of the Javadoc API is detected from the value of the <source/> parameter in the org.apache.maven.plugins:maven-compiler-plugin (defined in ${project.build.plugins} or in ${project.build.pluginManagement}), or computed via the Javadoc Tool executable. If you want to skip this link, you need to configure <detectJavaApiLink/> to false.

注意：如果您使用不受支持的JDK（如7.0），可以使用 < javaApiLinks /> 参数，即：

Note: if you are using an unsupported JDK like 7.0, you could add its Javadoc API url using the <javaApiLinks/> parameter, i.e.:

<configuration>
  <javaApiLinks>
    <property>
      <name>api_1.7</name>
      <value>http://download.java.net/jdk7/docs/api/</value>
    </property>
  </javaApiLinks>
  ...
</configuration>

请参阅 < links /> 参数以获取更多信息。

Refer to <links/> parameter for more information.

假设您在编译器插件中配置了1.6 源级别，则交叉引用指向Java API的链接工作（链接指向 http://download.oracle.com/javase/6/docs / api / ），没有为Java API添加任何东西。

Assuming you configured a 1.6 source level in the compiler plugin, cross references links to the Java API just works (links point to http://download.oracle.com/javase/6/docs/api/), there is nothing to add for the Java API.

<对我来说，两者都没有开箱即用。我不得不添加链接部分以使交叉引用工作。

Neither works out of the box for me. I had to add the links section to make the cross referencing work.

很奇怪。您是否实际指定了编译器 source 级别？以防万一，这对我有用：

Weird. Did you actually specify the complier source level as documented? Just in case, here is what works for me:

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
      <source>1.6</source>
      <target>1.6</target>
    </configuration>
  </plugin>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.7</version>
    <configuration>
      <!-- No need for this -->
      <!--
      <javaApiLinks>
        <property>
          <name>api_1.6</name>
          <value>http://download.oracle.com/javase/6/docs/api/</value>
        </property>
      </javaApiLinks>
      -->
      <links>
        <link>http://commons.apache.org/dbcp/apidocs/</link>
        <link>http://commons.apache.org/fileupload/apidocs/</link>
      </links>
    </configuration>
  </plugin>

这篇关于如何使javadoc继承适用于外部API？ （与Maven2）的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！