如何使javadoc继承适用于外部API？(与Maven2)

Question

当类重写具体方法或实现和抽象方法时,除非显式覆盖,否则Javadoc会自动继承.

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

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

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

<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>

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

Answer 1

正如@Stephen所提到的,继承方法的源文件必须可用,并且必须位于指定的路径上-sourcepath.这在Javadoc工具文档中有解释:

自动复制方法注释

Javadoc工具能够在以下两种情况下复制或"继承"类和接口中的方法注释.构造函数,字段和嵌套类不继承doc注释.

• 自动继承注释,以填补缺失的文字 -当主说明,或@return, @param或@throws标签被从一个方法注释丢失,从方法的Javadoc工具拷贝相应的主描述或标记注释它覆盖或实现(如果有的话),根据下面的算法.

  更具体地说,当@param缺少特定参数的标记时,将从继承层次结构中的方法复制该参数的注释.如果@throws缺少特定异常的 @throws标记,则仅在声明该异常时才复制标记.

  此行为与版本1.3及更早版本形成对比,其中任何主要描述或标记的存在将阻止所有注释被继承.

• 使用{@inheritDoc}标记显式继承注释 - {@inheritDoc}在方法主要描述中插入内联标记@return, @param或者@throws标记注释 - 将相应的继承主要描述或标记注释复制到该位置.

继承方法的源文件只需要在-sourcepathdoc注释指定的路径上实际可用于复制.类和其包都不需要在命令行上传递.这与1.3.x及更早版本形成对比,其中该类必须是文档类

因此,您必须使用<sourcepath>javadoc插件的可选配置参数(默认情况下包含项目的源).

顺便说一句,<links/>是其他东西,<links/>用于添加交叉引用链接到外部项目.实际上,它们不应该用于JDK.从配置链接:

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

注意:如果您使用不受支持的JDK(如7.0),则可以使用<javaApiLinks/>参数添加其Javadoc API URL ,即:

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

<links/>有关更多信息,请参阅参数.

假设您source在编译器插件中配置了1.6 级,交叉引用指向Java API的链接正常工作(链接指向http://download.oracle.com/javase/6/docs/api/),没有任何内容可供添加Java API.

对我来说,它们都不是开箱即用的.我不得不添加链接部分以使交叉引用工作.

奇怪的.您是否实际指定了记录的编译器source级别？以防万一,这对我有用:

  <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>