Re: Javadoc Comment Formatting

[Eric Blake]

I am not opposed to doing better markup of comments in my code.  As I
write doc comments, I have been trying to make formatted lists
correctly, use &lt; instead of <, and other things; but I do not always
get it correct.  Further, I have not tested my documentation work by
running it through any tool, free or from Sun, so I'm sure I have
contributed buggy comments.  When I code, I prefer to consult
well-formatted HTML, XML, or texinfo comments than trying to read
comments inline.  One reason is that a well-done markup version has
hyperlinks that inline code does not, and as nice as etags is for emacs,
it's not perfect.

I agree with the sentiment that the final output is worth the reduced
readability in the source code, but I am willing to go with the majority
on this decision, whichever way it gets decided.

Julian Scheid wrote:
> 
> 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.
> 

-- 
This signature intentionally left boring.

Eric Blake             address@hidden
  BYU student, free software programmer