Name: nt126004 Date: 03/11/2002


FULL PRODUCT VERSION :
java version "1.3.1_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_01)
Java HotSpot(TM) Client VM (build 1.3.1_01, mixed mode)

FULL OPERATING SYSTEM VERSION :
Microsoft Windows 2000 [Version 5.00.2195]


A DESCRIPTION OF THE PROBLEM :
It is useful to provide inline links to the
#package_description bookmarks because many people don't
seem to grasp the intent of the "See: Description" link
that Javadoc provides on package pages. However, it is
difficult to link to the bookmark. There does not appear to
be any documentation on the syntax for including a bookmark
in an @link tag.

Three cases are described below (I need to describe them
all in a single report, as they are inter-related). The
first one may sound like a mere inconvenience, but it has
ramifications that are explained in the third case:

1. To include a link from an interface description to the
#package_description bookmark on a package page, this
syntax does not work:

{@link com.xxx.somepackage#package_description}

As a workaround, this HTML syntax can be used instead of
the @link in interface descriptions:

{@docroot}/com/xxx/somepackage/package-
summary.html#package_description">com.xxx.somepackage
description</a>

However, it seems like using @link would be more reliable
for error-checking.


2. You cannot add a normal HTML bookmark in the first
sentence on the package page using this syntax:

<A HREF="#package_description">description</a>

Although this works fine on the package page itself, it
does not work when the first sentence is included in the
package table on the Overview page, as it resolves to
overview-summary.html#package_description.


3. The workaround for item (1) above fixes the Overview
page problem described in item (2), BUT it causes the
Javadoc tool to fail to parse the @link tags on the package
summary page! For example, if the package page says
something like this:

---------
<p>This package contains information about
sometopic.&nbsp;For more information, see the
{@docroot}/com/xxx/somepackage/package-
summary.html#package_description">com.xxx.somepackage
description</a> below the "Class Summary" table.</p>
<p>The most useful interface in this package is the {@link
com.xxx.somepackage.Foo} interface....</p>
---------

The output ends up looking like this in the full package
description, where the "{@link...}" appears literally:

---------
This package contains information about sometopic. For more
information, see the com.xxx.somepackage description below
the "Class Summary" table.

The most useful interface in this package is the {@link
com.xxx.somepackage.Foo} interface....
---------


STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Try the syntax examples in the description (with real
names)
2. Check the results in the Overview, package, and
interface pages.

This bug can be reproduced always.

CUSTOMER WORKAROUND :
Workaround doesn't quite fix the problem. See the Synopsis.
(Review ID: 139891)
======================================================================