Path: utzoo!attcan!uunet!snorkelwacker!usc!cs.utexas.edu!uwm.edu!mrsvr.UUCP
From: weiss@mrsvr.UUCP (Reinhard Weiss)
Newsgroups: comp.lang.c
Subject: Re: C documentation
Message-ID: <2856@mrsvr.UUCP>
Date: 31 Jul 90 16:15:26 GMT
References: <58440@bbn.BBN.COM>
Sender: news@mrsvr.UUCP
Lines: 60

From article <58440@bbn.BBN.COM>, by dwilbert@bbn.com (Deborah Wilbert):
> Hi,
> 
> I am looking for ways to generate documentation from C source code.
> I'm not sure what it can/should do aside from extracting headers and
> comments, which would be pretty simple. I would be open to inserting
> keywords into the C source comments to format the generated document.
> 
> Public domain software would be best. I am also vaguely interested in
> other documentation aids, such as static flow analysis tools.
> 
> Thanks for any leads,
> Deborah Wilbert

Although it is not the most elegant way of doing things, we use keywords
in our software to extract headers for purposes of documentation.  We 
don't add comments, however, because our headers are quite extensive.
An example follows:

/* "DESC:1
*********************************************************************

  Function:      fooProgram

  Purpose:       generates lots of foo.

  Global Data:   input:  none
                 output: none

  Interrupt Compatibility: this program generates a lot of foo, don't
                 use/call from an ISR

  Returns:       (int) the status of this function

  Errors:        hardware errors result in a core dump, software errors
                 are reported (return value) as follows:

                 0 - everything is OK
                 etc.

  Details:       Function begins by setting up the hardware to generate
                 as much foo as the user can possibly handle.  Initialization
                 takes place by (blah, blah, blah).

  _Generation_   _Date_     _Author_         _Comments_

    01.01.01   07-31-90  Reinhard M. Weiss   First pass

***********************************************************************
  "ETC
*/


The command to extract the header is then:

sed -n -e '/DESC/,/ETC/p' file_name

(Oh, by the way, this is on unix.  I can't speak for any other OpSystems.)
If your finicky and want to group in comments as well, just put the
keywords around the comments.