Re: Extending javadoc for C/C++

r.m.muench@ieee.org (Robert M. Muench)
13 May 1997 22:43:01 -0400

          From comp.compilers

Related articles
[2 earlier articles]
Re: Extending javadoc for C/C++ dwight@pentasoft.com (1997-05-08)
Re: Extending javadoc for C/C++ nr@adder.cs.virginia.edu (Norman Ramsey) (1997-05-08)
Re: Extending javadoc for C/C++ richardm@cogs.susx.ac.uk (1997-05-08)
Re: Extending javadoc for C/C++ objsoft@netcom.com (1997-05-08)
Re: Extending javadoc for C/C++ ercs50@tattoo.ed.ac.uk (1997-05-12)
Re: Extending javadoc for C/C++ amoroso@mclink.it (1997-05-12)
Re: Extending javadoc for C/C++ r.m.muench@ieee.org (1997-05-13)
| List of all articles for this month |

From: r.m.muench@ieee.org (Robert M. Muench)
Newsgroups: comp.compilers
Date: 13 May 1997 22:43:01 -0400
Organization: SCRAP-EDV Anlagen GmbH
References: 97-05-085
Keywords: documentation, C, C++

first have a look at DOC++ this is the best one I found yet in this
direction. Produces LaTeX or HTML and is very easy to use.


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


Good suggestion. This would make it possible to switch to a different
tool if someone needs an other output-format. Here are some thoughts
about such a system (I wanted to code one myself but don't have the
time... the concept is almost complete).


1.
No documentation tool can handle the three different documentation
needs:
- internal developer documentation: That are the docs from the
programmer/coder on theire own code.
- external developer documentation: That are the docs fro the public
interfaces and therefore for the 'usesers' of the code.
- user documentation: That are the docs describing how a function has
to be used from a users point of view. These parts should be collected
and presented to the technical writers in some way. So how about using
@docex
@docuser
for the two 'new' documentation types and leave the 'normal' tag for
the internal documentation type?


2.
There is a need to document the source-code, too!! Yet all these tools
only document the interfaces. I want to include a nice/pretty-printed,
well-documented source-code listing into my
specification/project-documents.


For this the following might be good:
@precondition
@postcondition


3.
There should be versioning info included.
@revision
@changes




Robert M. Muench
SCRAP EDV-Anlagen GmbH, Karlsruhe, Germany
==> Private mail : r.m.muench@ieee.org <==
--


Post a followup to this message

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