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

发布于 2024-09-12 22:06:00 字数 844 浏览 11 评论 0原文

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

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

原文

When a class overrides a concrete method or implements and abstract method, the Javadoc is automatically inherited unless explicitly overwritten.

Or, at least the tool tries to do this. It seems it does not work for linked external APIs. For instance, when I in my code implement java.util.Map, or something else from the JRE, the javadocs are not inherited/copied from the JRE javadocs/apidocs.

In my specific case, I am trying to configure this in the Maven2 Javadoc plugin, but it is the same when I run the javadoc CLI tool directly.

My Maven2 Javadoc plugin configuration currently looks like this:

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

Any pointers on how to make this work?

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

安静被遗忘 2024-09-19 22:06:00

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

自动复制方法注释< /a>
Javadoc 工具能够
复制或“继承”方法注释
下的类和接口
以下两种情况。
构造函数、字段和嵌套
类不继承文档注释。

自动继承注释以填充缺失的文本 - 当主要
描述，或@return，
缺少 @param 或 @throws 标签
来自方法注释，Javadoc
工具复制相应的main
描述或标签评论
它重写或实现的方法（如果
任意），根据算法
如下。
更具体地说，当特定的 @param 标记
缺少参数，则注释
因为该参数是从
方法进一步继承
等级制度。当 @throws 标签用于
缺少特定的异常，
仅当满足以下条件时才会复制 @throws 标记
声明异常。
此行为与 1.3 及更早版本形成对比，其中
存在任何主要描述或
标签将阻止所有评论
被继承。
使用 {@inheritDoc} 标记显式继承注释 - 插入
内联标记 {@inheritDoc} 在
方法主要描述或@return，
@param 或 @throws 标签注释 --
对应继承的main
描述或标签注释被复制
到那个地方。
继承的源文件
方法只需要在路径上
由 -sourcepath为文档评论实际上是可供复制。班级也不也不需要传入它的包在命令行上。这形成对比对于 1.3.x 及更早版本，其中该类必须是记录的类

所以你必须使用 javadoc 插件的可选配置参数（默认包含项目的源）。

顺便说一下，是别的东西，用于添加外部项目的交叉引用链接。实际上，它们不应该用于 JDK。来自配置链接：

自 2.6 起，将添加 Javadoc API 链接，具体取决于您的项目使用的 JDK 版本。从的值检测 Javadoc API 的版本 < 中的参数code>org.apache.maven.plugins:maven-compiler-plugin （在 ${project.build.plugins} 或 ${project.plugins} 中定义） build.pluginManagement}），或通过 Javadoc Tool 可执行文件计算。如果想跳过这个链接，需要配置 < code>为 false。
注意：如果您使用的是不受支持的 JDK（例如 7.0），您可以使用参数，即：
<前><代码><配置>;

<属性>
<名称>api_1.7
<值>http://download.java.net/jdk7/docs/api/

...
参考< /code>参数以获取更多信息。

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

这两种方法对我来说都不是开箱即用的。我必须添加链接部分才能使交叉引用发挥作用。

诡异的。您是否确实按照文档指定了编译器源级别？以防万一，这对我有用：

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

As @Stephen mentioned, the source file for the inherited method must be available and must be on the path specified by -sourcepath. This is explained in the Javadoc tool documentation:

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

So you'd have to use the <sourcepath> optional configuration parameter of the javadoc plugin (which contains by default the sources of the project).

By the way, <links/> are something else, <links/> are used to add cross reference links to external projects. And actually, they shouldn't be used for the JDK. From 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.

Assuming you configured a 1.6 source level in the compiler plugin, cross references links to the Java API just works (links point to http://download.oracle.com/javase/6/docs/api/), there is nothing to add for the Java API.

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

Weird. Did you actually specify the complier source level as documented? Just in case, here is what works for me:

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

回复收藏 0 原文