Extracting documentation from C code.

[Ivan Peters]

In article <BENNY.91May15185447 at dimona.vlss.amdahl.com>, benny at vlss.amdahl.com (Benny Schnaider) writes:
|> Hi,
|> 
|> I am looking for a utility to extract documentation from a "C"
|> program. I want to have the documentation source as part of the "C" code
|> (comments) which can be easily extracted in a troff (man page)
|> format. The output should be similar to man 3 output format.
|> 
|> Thanks,
|> Benny
|> --

Heres another way, among many...
We have the following format for standard headers in the src...

file headers:
/*M***************************************************************************
*
*   File Name:      filename.c
*
*   Description:    This module .....
*
*
*   Functions:
*                   function_name
*                   function_name
*
*
*
*
*   Revision History:
*   Date        Engineer        Comment
*   mm/dd/yy    I. Software     xxxxxxxxxxxxxxxxxx
*
****************************************************************************M*/
functions in files:
/*F****************************************************************************
*
*   Function Name:  function_name
*
*   Description:    This function ..
*
*   Input:
*
*
*   Output:
*
*
*   Return:
*
*
*   Notes:
*
*
*
*
****************************************************************************F*/
include file headers:
/*I***************************************************************************
*
*   File Name:      filename.h
*
*   Description:    Common equates for files
*
*
*   Revision History:
*   Date        Engineer        Comment
*   mm/dd/yy    I. Software     xxxxxxxxxxxxxxxxxx
*
****************************************************************************I*/

I have a combination awk/sed script that will generate manpages of the stuff
in those headers as follows:


awk '/\*M\*/,/\*\*M\*/
     /\*F\*/,/\*\*F\*/
     /\*I\*/,/\*\*I\*/' | \
sed -e 's%\/\*F\*%    %g' \
    -e 's%\*F\*\/%    %g' \
    -e 's%\/\*M\*%    %g' \
    -e 's%\*M\*\/%    %g' \
    -e 's%\*% %g' |\
awk '
BEGIN { f=0 }
{if (($1 ~ /File/) && ($2 ~ /Name/)) { {print ".TH",$3, "3"} ; f++}
else {if ($1 ~ /Description\:/) {print ".SH",$0}
else {if ($1 ~ /Functions\:/) {print ".SH",$0}
else {if (($1 ~ /Revision/) && ($2 ~ /History\:/)) {print ".SH",$0}
else {if (($1 ~ /Function/) && ($2 ~ /Name\:/)) {print ".TH",$3, "3"}
else {if ($1 ~ /Input\:/) {print ".SH",$0}
else {if ($1 ~ /Output\:/) {print ".SH",$0}
else {if ($1 ~ /Return\:/) {print ".SH",$0}
else {if (f > 0) {print $0 }  }
}
}
}
}
}
}
}
}
' | \
awk '
BEGIN {n=0}
{ for (i=1; i<=NF; i++)
    {{printf "%s ",$i}
    {if (i ==NF)
       {
       {printf "\n"}
       {n++}
       }
    }
}
}
{if (NR >= n+1 ) {
    {printf "\n"}
    {n = NR}
}
}
------------------
Known bug: It strips any info, on the same line (following) a key word.
  example: Description xxxxx          (will remove xxxxx)
This can easily be fixed with a awk function but I did not have the time yet.

Since this is a awk/sed script, it is easily modified, and portable.  One
can change the keyword searches, in the comments to whatever...  One could
also change this for other comment styles/headers/src other than 'c' easily.

Excuse me for useing awk/sed (for you alt lang types) in advance.   Perl
might be able to do this easier, but I have not yet graduated from awk/sed 
land yet...  :-).

This generates the man format.

(If you see him, Say hi to Mark Schrandt at Amdahl for me...:-) )