C documentation
Reinhard Weiss
weiss at mrsvr.UUCP
Wed Aug 1 02:15:26 AEST 1990
>From article <58440 at bbn.BBN.COM>, by dwilbert at 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.
More information about the Comp.lang.c
mailing list