John Keiser writes:
> I am curious: just how tied to Java is this, besides being written in it?
> What kind of work would it take to make it work with something like C/C++?
> A generic system that could generate doc-comments and do cross-linking and
> todo lists would be a very useful thing for other projects.
Ideally, it should break down into an ANTLR generated parser
module for Java, C++, C (insert language here), which
identifies snipplets of the embedded documentation
(e.g. /** ... */ blocks. doc++ also supported /// for single
line comments interleaved e.g. in method argument lists).
The documentation snipplets should be the programming
language independend part. If you abandon HTML markup and
go for DocBook XML instead, maybe javadoc /** */ blocks
should be ignored or handled differently. Difficult to
make sure that javadoc ignores your's, and you ignore
javadoc - "/***" or so doesn't work that well.
Labelling comment blocks is not necessary for those that
implicitely apply to the following class, method or
variable/argument, but it might add flexbility
e.g. for intergrating them into a separate document.
I have to look up the SGML literal programming pages
again, e.g. SWEB: an SGML Tag Set for Literate Programming
http://www.uic.edu/~cmsmcq/tech/sweb/sweb.html
Comment blocks from within the method body (particulars
of implementation) should be possible. But aside from
the "wishlist", I think the following distinction
is important:
- comment extraction (snip out /** .. */)
- comment filtering (remove leading * etc.)
- comment expanding (add the info from parsing actual code)
- comment insertion (merge into a document)
In the end, you should have a regular DocBook document.
All following processing could be done using whatever
DocBook backends are available. No XML/SGML parsing should
be done during the four steps above. The doclet API might
be useful for the above, but I'd not use it for the
actual rendering of the resulting document.
There is no need to be DTD specific except for the expanding
step - the target DTD needs to be aware of the elements to
which the Java declarations are mapped. One of the comments
could state which DTD to use (the per-file comment block,
if you will).
b.
