Re: Extending javadoc for C/C++

Steve Masticola (masticol@scr.siemens.com) wrote:
: - javadoc is the most widely-accepted mechanism for embedded
: documentation in C-like languages.


I'd also be interested in the answer to this. I plan on hacking one
up, with perl, for my Gri graphing language (pointer to which is in my
homepage). But mine won't be at all general. I have discovered one
thing already: I need a new marker,


@default


to add to @author and the others. For this reason, I suggest folks on
this group discuss a wish-list for possible additions to the javadoc
markers. That might be of aid to others, so that folks don't choose
too many different paths. For example, it might also make sense to
have a token called '@algorithm', an item which is often secondary to
readers' interests and which should therefore probably be separated
from the main description of the code. The advantage of discussing
this on the net is preventing one group calling this @algorithm and
another @method or some-such.


: - The best competitor, Don Knuth's "literate programming" and CWEB
: (http://www-cs-faculty.Stanford.EDU/~knuth/books.html) have not taken
: off in widespread practice, for whatever reason.*


I agree with the reason given. Knuth's is too complicated.
Unfortunately, I am EXACTLY in the category for which Knuth's scheme
is best suited: I'm a scientist who often needs to describe code by
complex formulae (e.g. differential equations with lots of partial
derivatives, etc), and for these the mathematical typesetting of TeX
is ideal. However, nobody in my research group has chosen to use
literate programming -- it just seems too difficult in practice. In
fact I've never seen scientific code with 'literate' comments.


Dan E. Kelley internet: mailto:Dan.Kelley@Dal.CA
Oceanography Department phone: (902)494-1694
Dalhousie University fax: (902)494-2885
Halifax, NS, CANADA, B3H 4J1 http://www.phys.ocean.dal.ca/~kelley
--

Return to the comp.compilers page.
Search the comp.compilers archives again.