How do you link to a _package description_ (not class) in the javadoc?

Question

(no, this is not a duplicate, see below)

For what it's worth, this is Oracle JDK, 7u72.

I cannot manage to link to the package description although I do need to, since important information is mentioned in there, but I fail to do so each time; when I try and {@link my.package.name} or tell people to go and @see my.package.name (or even a link to a package description of an external library), the javadoc tool reports that it cannot find the link...

So, how do I make such links?

---

OK, so, it is told that here is the answer, but no:

• the proposed solution only works for packages inside your own code; I want to be able to link to the package description of other libraries;
• I want such links to be valid in package-info.java and "plain" class javadoc as well.

So, this is NOT a duplicate.

Answer 1

It's not as simple as using the {@link package.class#member} tag syntax, but you can link to package documentation by using straight <a href="..."> HTML markup. The key is knowing the correct URI to place in the href attribute.

Javadoc outputs files arranged in a directory tree that matches your package structure. For each package, its description is always contained in a file named package-summary.html located within its corresponding directory. The actual description text is located at or near a particular anchor, which varies by Doclet version. The anchor name can be appended as a fragment identifier to any of the URIs below if you wish to jump directly to the description body instead of the top of the package page.

• In Java 7, the package description anchor was named description, represented as the fragment identifier #description.
• In Java 8, the anchor was renamed package.description, represented as the fragment identifier #package.description.

Local documentation (navigating packages within your own code):

• In any class, to refer to its own package:
  <a href="package-summary.html">link text</a>

• In class com.example.foo.MyClass to refer to the com.example parent* package:
  <a href="../package-summary.html">link text</a>

• In class com.example.foo.MyClass to refer to the com.example.bar sibling* package:
  <a href="../bar/package-summary.html">link text</a>

• In class com.example.foo.MyClass to refer to the com.example.foo.fizz.buzz child* package:
  <a href="fizz/buzz/package-summary.html">link text</a>

These examples all assume that the target packages are actually packages; in other words, that classes exist at that level. If instead com.example were a common prefix for all the packages but not a single class declared package com.example; then the second example above will be a dead link because no summary file will have been generated at com/example/package-summary.html.

The biggest drawback is that refactoring tools are unlikely to fix links in your Javadoc if you restructure or rename your packages.

*^{Yes, I understand that logically, in Java, packages have no official "parent" or "child" relationships. However, the directory structure used to organize files into packages does have parent-child semantics, and that's what I'm referring to here.}

Remote documentation (linked from a URL or file path):

Linked documentation works essentially the same way as local documentation, but with different anchor tag HREF targets. For example, linking to public documentation on the Web will use an absolute http:// address. Linking to another library somewhere else on your local or corporate filesystem might use relative or absolute paths as well.

Keep in mind that when using the link feature of the Javadoc tool, it is doing basically the same thing. It reads a package-list file from the linked directory tree to know which packages exist on the remote side, and then any referenced documentation from those packages use the appropriate URI in the generated links.

For example purposes, assume you're linking to the Java API from:
http://docs.oracle.com/javase/7/docs/api/

Then to refer to the java.util.concurrent package description, append the java/util/concurrent/ directory structure to the base URI, and add package-summary.html at the end. (Or just copy it from your Web browser.) :-)

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

Again, there is a drawback that if the external API documentation moves (ahem, Oracle) then when you update your Javadoc configuration to point to a new link, your {@link ...} tags may work but any handwritten HTML markup to these package files will be out of date.