7

当一个类重写具体方法或实现和抽象方法时，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>

关于如何进行这项工作的任何指示？

4

3 回答 3

6

正如@Stephen 提到的，继承方法的源文件必须可用，并且必须位于-sourcepath. Javadoc 工具文档中对此进行了解释：

自动复制方法注释

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

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

    更具体地说，当@param缺少特定参数的标记时，该参数的注释会从方法中复制到继承层次结构的更上层。当@throws特定异常的标记丢失时， @throws仅当声明该异常时才会复制该标记。

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

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

继承方法的源文件只需要-sourcepath位于 doc 注释指定的路径上，即可实际复制。类和它的包都不需要在命令行中传入。这与 1.3.x 和更早版本形成对比，其中类必须是文档类

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

顺便说一句，<links/>是别的东西，<links/>用于向外部项目添加交叉引用链接。实际上，它们不应该用于 JDK。从配置链接：

从 2.6 开始，将添加一个 Javadoc API 链接，具体取决于您的项目使用的 JDK 版本。 Javadoc API 的版本从（定义在或 中）中的<source/>参数值检测，或通过 Javadoc 工具可执行文件计算。如果要跳过此链接，则需要配置为.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/>参数。

假设您在编译器插件中配置了 1.6source级别，指向 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>
于 2010-08-04T04:45:03.070 回答
1

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

于 2010-08-04T00:27:13.967 回答
0

我在 StackOverflow 上有一个类似的问题，它比这个问题的公认答案更好地帮助我解决了这个问题：maven-javadoc-plugin and inheritDoc for Java API core classes

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

于 2016-08-02T05:39:29.800 回答