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工具文档中进行了解释：

Automatic Copying of Method Comments

Javadoc工具具有以下功能   复制或“继承”方法注释   类下面的类和接口   以下两种情况。   构造函数，字段和嵌套   类不继承doc注释。



自动继承评论以填写缺失的文字 - 当main description或@return时，   缺少@param或@throws标记   来自方法评论，Javadoc   工具复制相应的主要   来自的描述或标签评论   它覆盖或实现的方法（如果   任何），根据算法   下方。

更具体地说，当某个特定的@param标签时   参数丢失，然后是评论   从该复制的参数   方法进一步继承   层次结构。当@throws标记为   特别的例外是缺失的   仅在复制时才复制@throws标记   宣布异常。

这种行为与版本1.3及更早版本形成鲜明对比   存在任何主要描述或   标签会阻止所有评论   被继承。



使用{@inheritDoc}代码明确继承评论 - 插入   内联标记{@inheritDoc}   方法主要说明或@return，   @param或@throws标记评论 -   相应的继承主   描述或标签评论被复制   进入那个地方。



继承的源文件   方法只需要在路径上   由-sourcepath指定   文件评论实际上是   可以复制。不上课   也不需要传递其包裹   在命令行上。这与此形成对比   1.3.x及更早版本，其中   班级必须是documented class

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

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

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

注意：如果您使用的是不受支持的JDK，例如7.0，则可以使用<javaApiLinks/>参数添加其Javadoc API网址，即：
<configuration>
  <javaApiLinks>
    <property>
      <name>api_1.7</name>
      <value>http://download.java.net/jdk7/docs/api/</value>
    </property>
  </javaApiLinks>
  ...
</configuration>
有关详细信息，请参阅<links/>参数。

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

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

怪异。您是否实际指定了编译器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>

Answer 2

我不能给你一个明确的答案，但我认为谜题中缺少的部分是javadoc实用程序需要能够找到相关外部的源代码用于javadoc继承的API。

Answer 3

我在StackOverflow上有一个类似的问题，它帮助我更好地解决了这个问题，而不是这个任务的接受答案：maven-javadoc-plugin and inheritDoc for Java API core classes

<强>要点：为了从Java核心类继承Javadoc，您需要解压缩它们的源并将它们包含在Javadoc构建中。 Java核心类的源代码在JDK发行版中的src.zip文件中提供。

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

3 个答案:

Automatic Copying of Method Comments

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

3 个答案:

Automatic Copying of Method Comments

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