Sun Generating Invalid JavaDoc

Thread view:

Roedy Green - 09 Jan 2006 07:45 GMT

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.

Signature

Canadian Mind Products, Roedy Green.
http://mindprod.com Java custom programming, consulting and coaching.

Reply to this Message

Stefan Schulz - 09 Jan 2006 14:01 GMT

> 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.

Reply to this Message

Adam Warner - 12 Jan 2006 01:01 GMT

> JavaDoc generates links like this:
>
[quoted text clipped - 14 lines]
> 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

Reply to this Message

Sun Generating Invalid JavaDoc

Free Magazines