当类重写具体方法或实现抽象方法时，Javadoc 将自动继承，除非明确重写。

或者，至少该工具会尝试执行此操作。它似乎不适用于链接的外部 API。例如，当我在我的代码中实现 java.util.Map 或来自 JRE 的其他东西时，javadoc 不是从 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 工具文档中有解释:

Automatic Copying of Method Comments

The Javadoc tool has the ability to copy or "inherit" method comments in classes and interfaces under the following two circumstances. Constructors, fields and nested classes do not inherit doc comments.

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

  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.

  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.

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

The source file for the inherited method need only be on the path specified by -sourcepath for the doc comment to actually be available to copy. Neither the class nor its package needs to be passed in on the command line. This contrasts with 1.3.x and earlier releases, where the class had to be a documented class

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

顺便说一下，<links/>是别的东西，<links/>用于向外部项目添加交叉引用链接。实际上，它们不应该用于 JDK。来自 Configuring links :

Since 2.6, a Javadoc API link, depending the JDK version used by your project, will be added. The version of the Javadoc API is detected from the value of the <source/> parameter in the org.apache.maven.plugins:maven-compiler-plugin (defined in ${project.build.plugins} or in ${project.build.pluginManagement}), or computed via the Javadoc Tool executable. If you want to skip this link, you need to configure <detectJavaApiLink/> to false.

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 source在编译器插件级别，指向 Java API 的交叉引用链接正常工作(链接指向 http://download.oracle.com/javase/6/docs/api/ )，无需为 Java API 添加任何内容。

Neither works out of the box for me. I had to add the links section to make the cross referencing work.

奇怪。你真的指定编译器了吗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>

关于java - 如何使 javadoc 继承适用于外部 API？ (使用 Maven2)，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/3401642/