Re: Toward better Javadoc
Roedy Green wrote:
Something has always disgusted me about Javadoc -- that you are
supposed to embed unreadable HTML in your program comments.
You are supposed to embed HTML in Javadoc comments, sometimes. No one
requires that it be unreadable.
This makes them often unusable for those who need them most.
Only if you do it wrong.
I have done quite a bit of thinking about the problem, and I have
composed list of the Javadoc negatives and suggested solutions. It
requires the expressive power of HTML to explain.
Isn't that ironic?
See
http://mindprod.com/jgloss/javadoc.html#YUCH
To display
m??nus t??lf ????sund og ??rj?? hundru?? fj??rut??u og fimm
I embedded in a test class 'Generitor' the comment:
/** Generitor.
* m??nus t??lf ????sund og ??rj?? hundru?? fj??rut??u og fimm
*/
and got in the generated HTML, as viewed in Firefox or Konqueror:
Generitor. m??nus t??lf ????sund og ??rj?? hundru?? fj??rut??u og fimm
So the answer to your question:
Would it not be so much nicer if could be coded ... in plain text Unicode[?]
is, it can!
Did you actually try this yourself before writing your complaint?
If the encoding of the generated HTML is embedded as utf-8,
then there is no need for accented character entities in
the generated HTML. There is no need for entities either in
the Javadoc. You could encode awkward characters in your in
your comments with or without entities.
That's how it works now, with the exception of '&', '<' and '>'.
It uses old-style upper-case tags.
I've only ever used lower-case tags in Javadoc comments. Not once have I used
upper-case tags.
Define a canonical format for Javadoc comments and have
IDEs reformat as a matter of course when source code is tidied.
This would include collapsing multiple blank lines to one,
aligning the stars etc.
NetBeans and, IIRC, Eclipse do this. Doesn't your IDE?
Teach IDEs the conventions so they
warn you right away of malformed HTML in Javadoc comments,
NetBeans and, IIRC, Eclipse do this. Doesn't your IDE?
and [have] Javac [sic] treat... them as warnings.
The point of Javadoc comments is that they are *comments* and not covered by
'javac'. IOW, fundamentally they are intended to be ignored by 'javac'.
Perhaps you meant have 'javadoc' treat them as warnings?
For a Javadoc comment without embedded HTML tags,
treat them [sic] as if they had been enclosed in <pre> ??? </pre>
That would break a lot of existing Javadoc comments and be a fundamental
change. Personally I prefer the way it's done now.
--
Lew