[Doc-SIG] Documentation tool

[Mark Hammond]

>> I dont know what [JavaDoc formatting is like].  Is it possible to
>> summarize?
>
>Yep. You start a comment with "/**" (instead of "/*", and add in a
few
>magic tags.  As in:

This is almost identical to "autodoc", the tool I wrote about before
to the SWIG List (Ive suggested that SWIG generate this sort of
documentation directly in the sources).

When I suggested something like this a while ago to the DOC SIG, the
consensus was that it does not scan well enough for humans.  People
thought that the doc strings should be less intrusive than that.

But FWIW, I tend to agree with you.  My stated philosophy is that I
will sacrifice some readability in the source code comments if the
result is superior documentation - which I think this would provide.

And another FWIW, I have literally _thousands_ of lines of C code
all documented in this format (which is what builds the Windows help
files).  So whatever the DOC SIG does, I will always keep this
format around for something :-)

Mark.