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

时间:2014-12-13 19:17:07

标签: java javadoc

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

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

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

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


好的,所以,它被告知here是答案,但没有:

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

所以,这不是重复。

1 个答案:

答案 0 :(得分:2)

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

Javadoc输出与您的包结构匹配的文件arranged in a directory tree。对于每个包,其描述始终包含在其相应目录中名为package-summary.html的文件中。实际的描述文本位于特定锚点处或附近,具体取决于Doclet版本。如果您希望直接跳转到描述主体而不是包页顶部,则锚名称可以作为fragment identifier附加到下面的任何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中,包没有官方的#34;父母&#34;或者&#34;孩子&#34;关系。但是,用于将文件组织到包中的目录结构具有父子语义,这就是我在这里引用的内容。

远程文档(从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文档移动( ahem ,Oracle),那么当您更新Javadoc配置以指向新链接时,您的{@link ...}标记可能会但是这些包文件的任何手写HTML标记都将过时。