Re: Javadoc Comment Formatting

[Julian Scheid]

Nic Ferrier wrote:
> But none of that is really important. The bottom line is: you will
> never get all the authors of source code to write well-formed XHTML,
> you're always going to miss something. That's why it sucks.

OK if this is the problem, let me put it that way:

If we _aim_ towards having 100% well-formed XHTML comments, by
asking developers to close their open tags etc., the XML doclet
would have less trouble outputting valid XML code, which in
turn would lead to a higher-quality HTML documentation (and
other documentation generated via XSLT.)

Besides, as I mentioned before it would be quiet easy to
write a doclet which checks every comment for well-formedness.
Actually, XML doclet is already quiet tolerant and with a
few added out.printlns could provide you with information like
e.g. this:

WARNING: in java.lang.Number.compareTo(Object) comment (near line 123):
  (comment line 5) '<' taken as literal - tag looks like email address.

WARNING: in java.lang.String class comment (near line 42):
  (comment line 7) Unclosed <li> tag
  (comment line 8) Unclosed <li> tag

So "missing something" would only be possible when ignoring
these warnings.

WRT the readability issue: actually, a good deal of Classpath
javadoc comments completely lack any HTML tags and are
only formatted using indentation and line breaks. While this
is of course very legible when looking at the code, and may
produce good-looking (though non-standard) Info output, the
XML/XSLT solution will not be able to produce good-looking
HTML code from this (or any structured output other than plain
text-based formats).

I find this issue not paramount but in order to offer
high-quality documentation in various formats, I think we should
propose some guidelines for contributors, including the advice to
structure comments using (correct) HTML tags where necessary.
Reduces inline readability but enhances output readability,
integrity, portability and transformability. Wow!! ;)

Other opinions are very welcome.