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.
