java - 您如何链接到 javadoc 中的_包描述_(不是类)？

Question

(不，这不是重复的，见下文)

就其值(value)而言，这是 Oracle JDK，7u72。

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

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

---

好的，所以，被告知here是答案，但不是:

• 建议的解决方案仅适用于您自己代码中的包；我希望能够链接到其他库的包描述；
• 我希望此类链接在 package-info.java 和“普通”类 javadoc 中也有效。

所以，这不是重复的。

Answer 1

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

Javadoc 输出文件 arranged in a directory tree与您的包结构相匹配。对于每个包，其描述始终包含在名为 package-summary.html 的文件中位于其相应的目录中。实际的描述文本 位于特定 anchor 处或附近，这因 Doclet 版本而异。 anchor 名称可以附加为 fragment identifier如果您希望直接跳转到描述正文而不是包页面顶部，请转到下面的任何 URI。

• 在 Java 7 中，包描述 anchor 被命名为 description , 表示为片段标识符 #description .
• 在 Java 8 中， anchor 被重命名为 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 child * 包裹:
  <a href="fizz/buzz/package-summary.html">link text</a>

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

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

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

远程文档(从 URL 或文件路径链接):

链接文档的工作方式与本地文档基本相同，但具有不同的 anchor 标记 HREF 目标。例如，链接到 Web 上的公共(public)文档将使用绝对 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在末尾。 (或者只是从您的 Web 浏览器中复制它。):-)

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

同样，如果外部 API 文档移动(咳咳，Oracle)，那么当您更新 Javadoc 配置以指向新链接时，您的 {@link ...} 会再次出现一个缺点。标记可能有效，但这些包文件的任何手写 HTML 标记都将过时。