The API specification javadocs often include HTML anchor links of the form

    <a href="some/path/here">link text</a>

These are often improper, and they need to be audited and corrected. A telltale that indicates an improper link is a relative path with lots of ".." pathname elements. Usually these should be replaced with a different construct.

For example, consider the following fragment from jdk/src/share/classes/com/sun/jdi/ThreadGroupReference.java

     * See <a href="{@docRoot}/../../../../api/java/lang/ThreadGroup.html">java.lang.ThreadGroup</a>

The proper way to refer to another class in the JDK is to use @link for in-line references (@see for top-level references):

     * @link java.lang.ThreadGroup

A related issue is how to link to platform reference documents or the guides in the technotes areas. These documents are alongside the "api" directory (which contains the javadoc) and so should be specified relative to the document root @docRoot. Instead, many locations specify long chains of relative pathnames. This will usually work, but they will break if the text is included in a different page.

For example, in jdk/src/share/classes/com/sun/jdi/connect/spi/Connection.java there is the following:

     * <a href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html">

This should be replaced with:

     * <a href="{@docRoot}/../technotes/guides/jpda/jdwp-spec.html">

I've done a quick scan of the jdk repo for questionable links. This uses the following shell command:

    find . -name '*.java' -print | xargs egrep 'href=.*/\.\./\.\./'

The result is in the attached file badlinks.txt.

(This cuts across a large number of components, thus I wasn't sure which component and subcomponent to use.)