为什么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 Specification中的Package Summary以获取更多信息。”
3. 源文件基本上是超类、它们的超类（和接口）以及它们抛出的任何异常，这些异常也在同一个包中。唯一的例外是java.lang，我只需要获取Object。异常也是必需的，因为除了java.lang之外，其他包如果异常和抛出类在同一个包中，则无法链接。
4. 我用javadoc对我正在使用/子类化/抛出异常的所有包进行了注释。
5. 我将确保在概述文件中包括有关标准包和我的自定义包的一些信息。

不幸的是，目前我只能做一些变通措施，但我相信这可能是我的Java版本的问题。听起来其他人也遇到了类似的问题，并想出了自己的变通方法。这只是我的方法 =)

我仍然会接受回答，但在此期间，这是最方便的选择。非常感谢！

- user766413

---

通常情况下，如果继承类在源路径中但不在直接文档化的包列表中，它应该可以工作，就像Ted所写的那样。如果这种方式不起作用，您将需要展示一个JavaScript的调用示例，以及您的目录结构草图。（您可以编辑您的问题来添加这个信息。） - Paŭlo Ebermann

Answer 1

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

- Ted Hopp

---

在我的类似问题的答案中，有关如何执行此操作的更多详细信息。 - Paŭlo Ebermann

谢谢您的建议 =）实际上，这是我尝试的第一件事。听起来应该可以工作（我相当确定它曾经成功过），但现在对我来说却不起作用。我认为可能是我的Java版本有问题，但我还不想草率下结论。 - user766413

我记得在某个地方读到过，如果编译后的类在javadoc的类路径上，有时它会停止查找已编译的版本，并且不会在源路径上查找源代码；结果是注释最终没有被继承。我忘记是否有解决方法或者这是否与Java版本有关。我会四处寻找，如果有任何发现，我会再次发布评论。 - Ted Hopp

非常感谢，Ted Hopp。这并不适用于我发布的更简单的示例（UpperCaseObject），因为我确保没有先编译它。但是知道这一点会非常方便。 - user766413

Answer 2

你可以做的一件事是使用-link选项链接到这些类的官方Javadoc：

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 注释。

- Nathan Ryan

---

添加链接是一个好主意，但正如你所写的那样，它并不能解决“继承文档”的问题。 - Paŭlo Ebermann

@Paŭlo：没错，但是如果不包括 SDK 源代码，文档就无法被继承，因为这是 Javadoc 获取继承文档的机制。可以说，文档应该被引用而不是复制（虽然我认为在低层级进行复制也有其价值）。 - Nathan Ryan

正如Ted所写的（我几个月前为另一个类似的问题回答过），这是可以做到的，而不需要为JDK源代码生成新的文档。 - Paŭlo Ebermann

我从未意味着需要生成SDK类的Javadoc，只是源代码需要可用。 - Nathan Ryan

啊，我明白了混淆的原因。我的意思是，“引用而不是复制”，使用像 {@inheritDoc} 这样的机制或者继承文档会复制 文档 的文本。 - Nathan Ryan

这对我来说听起来是个好主意，但只有当我想强调这个子类的方法从其同名的超类方法中继承了重要信息时才会这样做。否则，这对我来说似乎有点多余。我更喜欢从Java的类中继承，就像我可以从同一包中的类中继承一样。 - user766413