Javadoc Comment Formatting

[Julian Scheid]

Some thoughts on the proper formatting of Javadoc comments
in this post.

First, let me point you to the "Sun Doc Check Utilities"
which I just stumbled over. They appear to be brand new:

<http://java.sun.com/j2se/javadoc/doccheck/index.html>

Might be useful for validating Classpath documentation.
Taken from that page:

 > DocCheck is an extension to the Javadoc tool that reviews
 > Javadoc comments in the source code, identifying gaps and
 > irregularities. It produces an HTML report that separates
 > serious problems from trivial ones, and makes "suggestions"
 > in the form of templates that show you what is needed.

Also, Sun seem to have updated their Javadoc style guide at
<http://java.sun.com/j2se/javadoc/writingdoccomments/index.html>
A good read IMO.

Now to the main issue, the formatting of the actual Javadoc
comment contents in Classpath. JLS 18.2 states that

 > Text in a documentation comment may use HTML markers for
 > formatting [...]

While this doesn't require, it certainly suggests that
documentation text basically is HTML code.

Now the Classpath comments do sometimes contain stuff like

  /**
   * ... maintained by <address@hidden>
   * ...
   */

and

  /**
   * ... for example,
   * <pre>
   *   if (a < b) { ... }
   * </pre>
   * ...
   */

That's no well-formed HTML of course, as the less-than signs
are normally interpreted as beginning-of-tag. I agree that

   *   if (a &lt; b) { ... }

isn't as readable as the original shown above (when looking
at the inline comments), but it's more correct in terms of
well-formedness. Gjdoc currently goes to some lengths to
recognize less-than signs that are not beginning-of-tag but
instead meant to stay as a literal character. But I think
in the long term, the proper solution is to adapt the comment
code and not the doclet driver.

 From my point of view, comment code would ideally be 100%
well-formed XHTML: all special characters expressed as XML
entities, all open tags closed, all tag attribute values in
quotes, all tags properly nested.
(For more information, see <http://www.w3.org/TR/xhtml1/#diffs>)

Thinking of the XML doclet described in my other mail, this
approach would ensure that we can generate any format from
the XML code via XSLT. If the HTML code in the comments is not
well-formed, XML doclet has to encapsulate it in CDATA
blocks, which renders the tags contained therein inaccessible
to the XSLT sheet.

For example, if a comment contained a bullet list (<ul>...</ul>),
a plain-text generating XSLT sheet would be able to correctly
transform that - but only if the comment code is a regular XML
node (which implies that it needs to be well-formed) and not
if the code is encapsulated as CDATA (which is necessary if
it isn't well-formed, as otherwise the whole XML file wouldn't
be well-formed).

Therefore I suggest that whoever cares about tidying up the
comments should also ensure that they adhere to the XHTML
standard - and everyone should ensure that all newly written
comments do. To this end, I could extend gjdoc so that it
is able to check comments for well-formedness and generate
warnings it they don't.

Perhaps I should also mention that Nic Ferrier has suggested
(and AFAIK actually started in his Paperclips project) to
use TexInfo formatting instead of HTML formatting in Javadoc
comments, arguing that TexInfo is the de-facto GNU
documentation standard and that TexInfo is better readable
than HTML when looking at the source code.

My opinion is, while TexInfo may be standard for GNU docs in
general, HTML is the standard for Javadoc comments. There are
plenty of tools (partly GPLed) already out there which operate
on Javadoc comments and expect them to be in HTML format
(including XML doclet.)

Also, TexInfo is a decent format but thinking of XSLT sheets,
X(HT)ML is more flexible as it allows generic transformations
to virtually any target format, while there is no
corresponding technology for transforming TexInfo code AFAIK.

For these reasons I don't share Nics point of view on this
issue. I think we (and any other GNU project) should stick
to using HTML in comments, preferrably well-formed XHTML.

--Julian