Re: Javadoc Comment Formatting

[Julian Scheid]

Nic Ferrier wrote:
> I do agree that XML is the way forward (docbook might make a good
> replacement for texinfo when it has widespread support like texinfo)
> but the issue of in-source readable comments will need to be solved
> before it is a really practical option.

It seems to boil down to inline readability and easy
comment maintenance on one hand, and full XHTML compliance
for enabling arbitrary XSLT conversions on the other.

I agree that strictly applying the XHTML standard will
degrade readability and add an additional burden for
documentation writers/maintainers, but for that you
gain 100% XML compliance with all eventual benefits.

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.)

> Can't you intelligently escape such things? for example if they don't
> turn out to be valid xml.

As I said, XML doclet already does something like this.
It even tries to guess where unclosed tags are ending
and inserts appropriate closing tags, to some extent.
But this is more of a hack and quiet error prone
- after all, it involves a lot of guessing if you have
input whose format is not defined umambigiously.

Julian