如何使javadoc继承适用于外部API？（与Maven2）

本文介绍了如何使javadoc继承适用于外部API？（与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:

 
   自动继承评论以填写缺失的文本  - 当，或 @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 - 插入
内联标记或 @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.

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

所以你必须使用 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:

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

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>

请参阅参数以获取更多信息。

Refer to <links/> parameter for more information.

假设您在编译器插件中配置了1.6 源级别，则交叉引用指向Java 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.

很奇怪。您是否实际指定了编译器 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）的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！

JavaDocs