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 :
 customer  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) 
======================================================================

N/A

Sent email to lisa:

Hi Lisa

Thank you for the well-written bug report.
We have already fixed case 3 in Javadoc 1.4.0

  Fixed {@link} with {@docRoot} - The {@docRoot} tag no longer disables 
  any {@link} tag that follows it in the same comment. (4369014)
 
  http://developer.java.sun.com/developer/bugParade/bugs/4369014.html

So I am inclined to close your bug out as a duplicate of 4369014.

See this page for other fixes in 1.4.0:
  http://java.sun.com/j2se/1.4/docs/tooldocs/javadoc/whatsnew-1.4.html

If you would like to re-submit the following as a new feature, please do so
in a separate request (or ask me to and I will for you):
 
 > 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}

It's an interesting idea that hadn't occurred to me.

regards,
  xxxxx@xxxxx   2002-03-11

Thinking further about this, @link with a package argument is designed to work 
only with program elements, not HTML named anchors.  While the syntax below
looks like it might work, using {@docRoot} is the proper way to go with 
named anchors.

  xxxxx@xxxxx   2002-03-30