继承Javadoc，而不为继承的源代码生成文档。

Question

我希望 class B 可以继承它实现的接口 interface A 的 Javadoc。我已在我的 Javadoc 命令中包含了 interface A 的源代码，并且 class B 正确地继承了文档。

现在我想知道是否可以使生成的链接指向网络上 interface A 的文档，而不是在我的网站上复制，即“Specified by:”链接将链接到外部页面。

这可能吗？

- Stuart K

Answer 1

是可以的，确实如此。 为了能够包含继承的文档，接口A的源代码必须在javadoc的源路径中可找到，但不应该在传递给javadoc用于文档创建的包列表中。 要进行链接，请使用-link参数。我刚刚尝试了这个（使用ant javadoc任务）：

<javadoc destdir="docs">
  <sourcepath>
    <!-- source of your class B -->
    <pathelement location="src" /> 
    <!-- source of external interface A -->
    <pathelement location="../example-src/src" />
  </sourcepath>

  <!-- your packages, to generate the docs for -->
  <package name="com.personal.myproject.*" />

  <!-- the location of the online documentation -->
  <link href="http://example.com/javadoc/"/>
</javadoc>

对于命令行的javadoc，我认为可以这样翻译（unix语法，一行）：

 javadoc -sourcepath ../example-src/src:src
         -d docs
         -link http://example.com/javadoc/
         -subpackages com.personal.myproject
         (other options...)

在这个例子中，

• B类 在包com.personal.myproject中，
• A接口 在包com.example中，
• 我自己的源代码在src中，
• 接口A的源代码在../example-src/src中。

对于为此创建的示例类，javadoc将会复制来自A.methodName()的文档到B.methodName()，但是链接到在线文档http://example.com/javadoc/com/example/A.html#methodName()。

感谢您提出这个问题，我一直想做这件事 :-)。

- Paŭlo Ebermann

---

谢谢你的回答，真的帮了我很多。事实证明，我在类路径中包含了一个相同类（“接口A”的）的jar文件，这导致继承的文档无法显示。 - Stuart K

Answer 2

非常感谢Paŭlo Ebermann的回答，为我的设置指明了正确的方向。请先阅读该答案，因为它可以解释清楚这个问题，而我只是提供了一种额外的配置解决方案。

---

所以，我想分享一下我使用的方法，供那些使用maven-javadoc-plugin作为构建过程中生成文档的一部分，并使用maven管理项目的人参考。

作为插件配置的一部分，您可以指定要包含的链接组。这里具体介绍了如何配置链接。

以下是一个示例，将selenium和java se的外部文档链接到一个jar包中，以便与我的项目一起部署。美妙的是，我的项目中的这些javadoc文档只是无缝地链接到外部文档。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <links>
            <link>http://seleniumhq.github.io/selenium/docs/api/java/</link>
            <link>https://docs.oracle.com/javase/${project.java.version}/docs/api/</link>
        </links>
    </configuration>
</plugin>

---

顺便说一句，如果您发现此页面上的任何内容有用，请在某个地方链接到它。在谷歌上找到这个页面太困难了，这是一个非常好的东西。

- Brian