Sun Generating Invalid JavaDoc

[Roedy Green]

JavaDoc generates links like this:

docs/api/java/applet/AppletContext.html#setStream(java.lang.String,_
java.io.InputStream)

where _ represents a space.

Note:
The HTML 4.01 spec section 6.2 states that anchor names must begin
with a letter a-z, A-Z, and may be followed by any number of letters,
digits 0-9, hyphens -, underscores _, colons :, and periods .. So lead
_ are not permitted. All numeric anchors are not permitted.

Note space, ( ) , are all illegal characters! Further Sun does not
even URL encode them.

So Sun is generating invalid HTML. This a bloody nuisance because it
means links into Sun JavaDoc won't validate.

 

[Stefan Schulz]

So Sun is generating invalid HTML. This a bloody nuisance because it

means links into Sun JavaDoc won't validate.

Links into as in <a href="...">The Javadocs</a>? I sincerely doubt
that.

Also, there is a lot of invalid html out there, and a good deal of that
from "reputable sources". So while i in principle agree that this ought
to be fixed, i don't think it is something i will get worked up about.

 

[Adam Warner]

JavaDoc generates links like this:

docs/api/java/applet/AppletContext.html#setStream(java.lang.String,_
java.io.InputStream)

where _ represents a space.

Note:
The HTML 4.01 spec section 6.2 states that anchor names must begin
with a letter a-z, A-Z, and may be followed by any number of letters,
digits 0-9, hyphens -, underscores _, colons :, and periods .. So lead
_ are not permitted. All numeric anchors are not permitted.

Note space, ( ) , are all illegal characters! Further Sun does not
even URL encode them.

So Sun is generating invalid HTML. This a bloody nuisance because it
means links into Sun JavaDoc won't validate.

Correct. You could use gjdoc from the GNU Classpath project. It provides
this option:

-validhtml
Force generation of valid XHTML code. This breaks compatibility to
the traditional Javadoc tool to some extent.

If this option is specified, anchor names will be mangled so that
they are valid according to the XHTML 1.1 specification.
However, a documentation set generated with this option cannot
be linked to properly using the traditional Javadoc tool. It
can be linked to just fine using Gjdoc, though.

Without this option, anchor names for executable class members use
the traditional format, for example: ‘‘foo(String,int[])’’. This
is compatible to the traditional Javadoc tool, but according to
both the HTML 4.0 and XHTML 1.0 and 1.1 specifications, this format
includes illegal characters. Parentheses, square brackets, and the
comma are not allowed in anchor names.

Regards,
Adam