你如何链接到javadoc中的_package description_(不是类)？

Question

(不,这不是重复,见下文)

对于它的价值,这是Oracle JDK,7u72.

虽然我确实需要,但我无法链接到包描述,因为那里提到了重要的信息,但我每次都没有这样做; 当我尝试{@link my.package.name}或告诉人们去@see my.package.name(甚至链接到外部库的包描述)时,javadoc工具报告它无法找到链接...

那么,我该如何建立这样的链接呢？

---

好的,所以,有人告诉我这是答案,但不是:

• 建议的解决方案仅适用于您自己的代码中的包; 我希望能够链接到其他库的包描述;
• 我希望这些链接在package-info.java和"plain"类javadoc中也有效.

所以,这不是重复的.

Answer 1

它并不像使用{@link package.class#member}标签语法那么简单，但您可以使用直接的<a href="...">HTML 标记链接到包文档。关键是知道要放置在href属性中的正确 URI。

Javadoc 输出的文件排列在与您的包结构相匹配的目录树中。对于每个包，其描述始终包含在其相应目录中名为的文件中package-summary.html。实际的描述文本位于特定锚点处或附近，该锚点因 Doclet 版本而异。如果您希望直接跳转到描述正文而不是包页面的顶部，则可以将锚点名称作为片段标识符附加到下面的任何 URI。

• 在Java 7中，包描述锚被命名为description，表示为片段标识符#description。
• 在Java 8中，锚被重命名package.description，表示为片段标识符#package.description。

本地文档（在您自己的代码中导航包）：

• 在任何类中，引用它自己的包：
  <a href="package-summary.html">link text</a>

• 在类中com.example.foo.MyClass引用com.example 父*包：
  <a href="../package-summary.html">link text</a>

• 在类中com.example.foo.MyClass引用com.example.bar 兄弟*包：
  <a href="../bar/package-summary.html">link text</a>

• 在类中com.example.foo.MyClass引用com.example.foo.fizz.buzz 子*包：
  <a href="fizz/buzz/package-summary.html">link text</a>

这些例子都假设目标包实际上是包；换句话说，阶级存在于那个层面。相反，如果com.example是所有包的公共前缀，而不是声明的单个类，package com.example;那么上面的第二个示例将是死链接，因为com/example/package-summary.html不会生成摘要文件。

最大的缺点是，如果您重构或重命名包，重构工具不太可能修复 Javadoc 中的链接。

*^{是的，我理解，从逻辑上讲，在 Java 中，包没有正式的“父”或“子”关系。然而，用于将文件组织到包中的目录结构确实具有父子语义，这就是我在这里所指的。}

远程文档（从 URL 或文件路径链接）：

链接文档的工作方式本质上与本地文档相同，但具有不同的锚标记 HREF 目标。例如，链接到网络上的公共文档将使用绝对http://地址。链接到本地​​或公司文件系统上其他位置的另一个库也可能使用相对或绝对路径。

请记住，当使用 Javadoc 工具的链接功能时，它基本上执行相同的操作。它从链接目录树中读取package-list文件，以了解远程端存在哪些包，然后这些包中的任何引用文档都在生成的链接中使用适当的 URI。

出于示例目的，假设您从以下位置链接到 Java API： http:
//docs.oracle.com/javase/7/docs/api/

然后引用java.util.concurrent包描述，将java/util/concurrent/目录结构附加到基本URI，并添加package-summary.html在最后。（或者直接从您的网络浏览器复制它。）:-)

http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html

同样，还有一个缺点，如果外部 API 文档发生移动（咳咳，Oracle），那么当您更新 Javadoc 配置以指向新链接时，您的{@link ...}标签可能会起作用，但这些包文件的任何手写 HTML 标记都将过时。