There are problems with invalid characters in
<A NAME="..."> identifiers generated by the standard doclet.

As I'm sure you know, the HTML spec section 6.2 states that:
http://www.w3.org/TR/html401/types.html#type-cdata

"# ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed
by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"),
colons (":"), and periods (".")."

The current method of making tags like
<A HREF="../../javax/swing/AbstractListModel.html#fireContentsChanged(java.lang.Object, int, int)">
probably can't continue if correct HTML is desired. Introducing < and > to
this for generics will probably break browsers that happen to tolerate the
current syntax (although they shouldn't have to.)

Name: boT120536 Date: 01/15/2001

===========================================================================

Example from <URL:http://java.sun.com/j2se/1.3/docs/api/java/lang/Object.html&gt;:

<A NAME="wait(long, int)"><!-- --></A><H3>
wait</H3>

The name attribute, though declared in the formal part of the DTD as
CDATA, is described in the prose as having name token syntax. This
means that the parenthesis, comma, and whitespace characters are not
permitted where javadoc puts them.

The two main problems with this stem from the whitespace in
particular:

1. It's impossible to write an URL containing such an invalid fragment-
    identifier in a plain-text context such as email. Either it's written
    naked, and is parsed as "...Object.html#wait(long" or it's enclosed
    with "<URL: ... >" brackets and the whitespace is ignored, giving
    "...Object.html#wait(long,int)".

    [Yes, sending the following URL by mail, the link stops at the space -Doug]
    http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#wait(long, int)

2. Browsers such as emacs-w3 that do their own whitespace stripping
    on passed URLs cannot follow links from other javadoc HTML, for
    the same reason.

My reading of the spec doesn't allow the use of "%" URL-escaping in
fragment identifiers, so perhaps a better scheme would be to use the
type codes as in the VM - eg "wait.JI" - perhaps using "-" instead of
";" to delimit class names.

Incidentally, the empty A element is probably a bad idea - the above
would be better written as <H3><A NAME="wait.JI">wait</A></H3>
(Review ID: 109616)