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

StackOverflow https://stackoverflow.com/questions/3401642

题

当类重写具体方法或实现和抽象方法时，除非显式重写，否则会自动继承 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>

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

有帮助吗？

解决方案

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

自动复制方法注释

Javadoc工具在以下两种情况下可以在类和接口中复制或“继承”方法注释。构造函数，字段和嵌套类不继承DOC注释。

  • 自动继承注释来填充缺失的文本 - 当一个 主要描述, ， 或者 @return, @param 或者 @throws 根据下面的算法，Javadoc工具从方法注释中缺少标签，Javadoc工具将其覆盖或工具（如果有）进行了相应的主要描述或标签注释。

    更具体地说，当 @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/> 中的参数 org.apache.maven.plugins:maven-compiler-plugin （定义于 ${project.build.plugins} 或在 ${project.build.pluginManagement}），或通过 Javadoc Tool 可执行文件计算。如果您想跳过此链接，则需要配置 <detectJavaApiLink/> 到 false.

笔记： 如果您使用的是不受支持的 JDK（例如 7.0），您可以使用以下命令添加其 Javadoc API url <javaApiLinks/> 参数，即：

<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 无需添加任何内容。

两者对我来说都不是开箱即用的。我必须添加链接部分才能使交叉引用起作用。

诡异的。您实际上指定了编译器吗 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>

其他提示

我无法给你一个明确的答案，但我认为，在拼图缺少的一块就是javadoc工具需要能够为找到的Javadoc继承的源代码相关外部的API工作

我有StackOverflow上类似的问题这有助于我更好地解决这个问题比这个questsion的接受的答案：的 Maven的Javadoc的插件和inheritDoc为Java API核心类

<强>要点： 为了继承Java核心类的Javadoc，您需要解压缩它们的来源，包括它们在Javadoc版本。都被在JDK发行版内的src.zip文件提供的Java核心类的来源。

许可以下： CC-BY-SA 和 归因
不隶属于 StackOverflow
scroll top