[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Javadoc Comment Formatting
From: |
Eric Blake |
Subject: |
Re: Javadoc Comment Formatting |
Date: |
Sun, 28 Apr 2002 17:24:09 -0600 |
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 < 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