[Cp-tools-discuss] Re: Javadoc Comment Formatting

[Nic Ferrier]

I'm not sure this should be discussed here but...


Julian Scheid <address@hidden> writes:
> 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. 

Personally I think that's the wrong way round. Javadoc is really
useful as an inline doc system as well as for producing a bunch of
nicely formatted doc pages.

Can't you intelligently escape such things? for example if they don't
turn out to be valid xml. Given the GNU coding standard you very
rarely see thing like this:

   * <pre>
   *   if (a<b)

which might be more difficult to spot as invalid than when there's a
space between the alphas and the operator.


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

But from the point of view of someone wanting to hack code quickly
the comments should be readable. Well-formed XHTML is not necessarily
readable.

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

Except info->SOMETHING drivers are quite easy to write and GNU has
lots of experience at them.


I do agree that XML is the way forward (docbook might make a good
replacement for texinfo when it has widespread support like texinfo)
but the issue of in-source readable comments will need to be solved
before it is a really practical option.

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

I just don't believe it's reasonable, it's hard enough to get people
to write code to the coding standard, let alone the doc comments.

The problem is that XHTML throws such spanners in the works, the
example you cited before is a really good one, so it this:

   /**
     * This is a method that writes some stuff.
     * The outputstream gets something like this:
     * <pre>
     *   this is the concat of a & b
     * </pre>
     

which of course won't work. Using the less than sign, the greater
than sign and other HTML reserved words is quite common in javadoc
comments and having to remember the HTML is a great big pain in the
neck.

The equivalent in texinfo, of course, does not cause such problems.


Nic