Re: Javadoc Comment Formatting

[Nic Ferrier]

Julian Scheid <address@hidden> writes:

> I'll leave that for discussion. My opinion is: make 
> comments XHTML compliant and ease the task for 
> writers/maintainers by supplying appropriate (XHTML 
> checking, and perhaps fixing) tools. Live with degraded 
> readability, or better: view the documentation generated 
> by Texinfo doclet instead of consulting inline comments. 
>  
> (Most of the time, you will be looking up docs for a 
> method different from that you are currently working on, 
> so in terms of keystrokes it isn't a big difference 
> whether you open another file and browse to the method 
> definition, or you open the info docs for that method 
> - provided you are using something like jtxd.el for 
> quick access to generated documentation.) 

It depends on what you're doing. If you're the maintainer of some
source code then you're right, whilst you're hacking it you are
probably looking up methods in other places (having said that all the
useful browser tools we have so far deal with source code files, not
a documentation tree).

But that isn't the only audience for source code, it's not even the
main audience (for most GNU code).

Most GNU code has a very long life and is hacked on by many people. I
hate picking up java code where there is XHTML javadoc because it's
so hard to read.


But none of that is really important. The bottom line is: you will
never get all the authors of source code to write well-formed XHTML,
you're always going to miss something. That's why it sucks.


Nic