为什么 Javadoc 不让我的子类从 Java 类继承文档？

Question

我几个月来一直在寻找答案，并且尝试了多种方法，包括解压缩压缩文件夹 src.zip 并将其用作 Javadoc 的参数（例如：javadoc -sourcepath src com.example.test）

这是 JDK 6 Update 24 附带的默认 Javadoc。

假设我正在开发一个实现 java.util.Map 接口的新地图。默认情况下，如果我没有记错的话，我从 Map 接口重写的方法应该继承接口的文档。然而，javadoc从来不这样做。

到目前为止，解决这个问题的唯一方法实际上是对 Java 编写的类进行 javadoc 处理（例如：javadoc com.example.text java.util）。我不想这样做，因为这看起来像是我重写了 Java 类，但这是唯一的方法吗？如果是的话，我想我可以忍受它，但我的理解是还有另一种方法可以做到这一点。

谢谢=）如果这有点混乱，我很抱歉。这是我第一次使用 Stack Overflow。如果这个问题已经被问过，我也很抱歉。我读过很多类似的问题，因为它们没有涵盖我想问的所有内容，而且我发现它们非常令人困惑，因为它们涉及编写您自己的 Javadoc 实现。无论如何，提前谢谢您 =)

编辑：5 月 25 日 4:44

好吧 =) 如果我理解正确，您希望看到一个示例。这是一个更简单的例子，我试图看看这是否是因为我正在尝试一些不应该起作用的东西。

package com.example;

/**
 * A simple class that returns an upper-case string representation.
 */
public class UpperCaseObject {

    @Override public int hashCode() {
        return super.hashcode();
    }

    /**
     * {@inheritDoc}
     *
     * <P>The {@code toString} method for class {@code UpperCaseObject} returns
     * converted to uppercase.</P>
     *
     * @see String#toUpperCase()
     */
    @Override public String toString() {
        return super.toString().toUpperCase();
    }

}

我将此示例（文件名为 UpperCaseObject.java）移至目录 javadoc-test/com/example 中，并且我还创建了另一个目录 javadoc-test/java /lang，将 Object.java（来自 src.zip）放入其中。

我对 javadoc 的调用是 javadoc -link http://download. oracle.com/javase/6/docs/api/ com.example 来自目录 javadoc-test。我的路径参数中有 jdk6 bin 目录。

我期望的两件事是 UpperCaseObject.hashCode 继承所有文档，以及 UpperCaseObject.toString 来自 java.lang.Object 的额外段落之前的所有内容。然而，不幸的是，我没有得到任何文档。

编辑：

嗯，我必须做的如下。这只是一个简单的解决方法。

1. 我像平常一样从 source.zip 复制了所有源文件。
2. 我还为每个包制作了包文件。它们包含第一段（带有摘要的段）和第二段，内容为“请参阅 Java™ Platform, Standard Edition 6 API 规范中的包摘要以获取更多信息。"
3. 源文件本质上是超类、它们的超类（和接口）以及它们抛出的任何异常，这些异常也位于同一个包中。唯一的例外是 java.lang，我只需要获取 Object。还需要异常，因为除了 java.lang 之外，如果异常与抛出类位于同一包中，则其他包不会链接。
4. 我对所有我正在使用/子类化/抛出异常的包进行了javadoc处理。
5. 我将确保在概述文件中包含有关标准包和我自己的包的一些信息。

不幸的是，我现在只能解决这个问题，但我确信这可能是我的 Java 版本的问题。听起来其他人也遇到过类似的问题并提出了自己的解决方法。这只是我自己的 =)

我仍然会接受答案，但这是同时最方便的选择。非常感谢！

Answer 1

继承方法的源文件在运行时需要位于 javadoc 工具的 -sourcepath 中。您不需要在命令行上传递继承的类。

Answer 2

您可以做的一件事是使用 -link 选项：

javadoc -sourcepath src -link http://download.oracle.com/javase/6/docs/api com.example.test

这将允许 Javadoc 将 SDK 的类视为“外部引用类”。来自 Javadoc 文档：

在 javadoc 运行期间未生成其文档的引用类。换句话说，这些类不会通过命令行传递到 Javadoc 工具中。生成的文档中指向这些类的链接被称为外部引用或外部链接。例如，如果仅对 java.awt 包运行 Javadoc 工具，则 java.lang 中的任何类（例如 Object）都是外部引用的类。可以使用 -link 和 -linkoffline 选项链接到外部引用的类。外部引用类的一个重要属性是其源注释通常不可用于 Javadoc 运行。在这种情况下，这些注释不能被继承。

请注意，这些类的 Javadoc 仍然不会被继承。但是，您现在可以链接到它，如下所示：

public class MyMap implements java.util.Map {
    ...
    /**
     * @see java.util.Map#isEmpty()
     */
    @Override
    public boolean isEmpty() {
        ...
    }
}

[编辑]

@see 标记用于说明。 Javadoc 应该自动生成一个“指定者”链接，因此您可以完全省略 Javadoc 注释。