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 [EMAIL PROTECTED] BYU student, free software programmer _______________________________________________ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
