你如何在javadoc中链接到“_包描述_”（而不是类）？

Question

值得一提的是，这是Oracle JDK 7u72版本。

我无法链接到包描述，尽管我需要，因为其中提到了重要信息，但每次都失败; 当我尝试{@link my.package.name} 或者告诉别人去 @see my.package.name （甚至是外部库的包描述链接），javadoc工具报告找不到链接...

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

---

好吧，据说这里有答案，但不：

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

因此，这不是重复问题。

- fge

---

https://dev59.com/RWw05IYBdhLWcg3wXAqF - SSC

@Mr.777 问题如第一个答案中所述的评论所示；而且，如果我想链接到外部库的包描述（比如 {@link java.nio.file}），那么这种方法就行不通了。 - fge

你尝试过使用 javadoc 的 -link 选项吗？ - Betlista

@Betlista 我已经有了Javadoc链接 -- 我可以轻松生成到JDK类的链接。只是无法链接到包描述... - fge

对不起，我误读了你的话。这是一个非常好的问题。Oracle指出"指向引用类的特定包、类或成员名称的文档"，但我们知道这也适用于接口和枚举类型。在维基百科的文章中，*@link的适用于下面并没有列出包*。当然，维基并不是官方文档。Oracle从未真正告诉我们如何引用包，但从未提到这是不可能的。这需要更好的文档说明。+1 - Dioxin

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">链接文本</a>

• 在类com.example.foo.MyClass中，引用com.example的父级*包：
  <a href="../package-summary.html">链接文本</a>

• 在类com.example.foo.MyClass中，引用com.example.bar的同级*包：
  <a href="../bar/package-summary.html">链接文本</a>

• 在类com.example.foo.MyClass中，引用com.example.foo.fizz.buzz的子级*包：
  <a href="fizz/buzz/package-summary.html">链接文本</a>

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

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

*^{是的，在Java中，逻辑上讲，包没有官方的“父”或“子”关系。然而，用于将文件组织成包的目录结构具有父子语义，这就是我在此处指的。}

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

链接文档与本地文档基本相同，但具有不同的锚标签HREF目标。例如，链接到Web上的公共文档将使用绝对的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标记都将过时。

- William Price