krf@sol.ral.rpi.edu (Keith R. Fieldhouse) (03/20/90)
Is there a generally available, simple, piece of software that will extract
specially formatted comments from source code (mostly C but others
would be nice) and produce printable documentation. What I have in mind
is something like the following:
/*
** .FUNCTION get-stuff()
** .PURPOSE
** Does really nifty things really fast and you can
** dance to it.
** .PARAMETERS
** a, integer that tells function what to do
** b, character that tells function what not to do
** .RETURN
** OK or ERROR
*/
int get-stuff(a,b)
int a;
char b;
...
Which would produce something like
<FF>
Function:
get-stuff
Does really nifty things really fast
and you can dance to it.
Parameters:
a -- an integer that tells function what to do
etc.
It doesn't have be very sophisticated, tangle/web/weave or info-tex are
really overkill for my purposes. I'm just looking for something where
the small discipline of documenting important functions correctly
provides the large benefit of printable basic documentation.
Any pointer will be appreciated.
- Keith
--
Keith R. Fieldhouse krf@ral.rpi.edu
Center for Intelligent Robotic (518) 276-6758
Systems for Space Exploration (CIRSSE) CII 8313
Rensselaer Polytechnic Institute Troy, New York 12180-3590lwall@jpl-devvax.JPL.NASA.GOV (Larry Wall) (03/21/90)
In article <DGA#'-*@rpi.edu> krf@sol.ral.rpi.edu (Keith R. Fieldhouse) writes:
:
: Is there a generally available, simple, piece of software that will extract
: specially formatted comments from source code (mostly C but others
: would be nice) and produce printable documentation. What I have in mind
: is something like the following:
:
: /*
: ** .FUNCTION get-stuff()
: ** .PURPOSE
: ** Does really nifty things really fast and you can
: ** dance to it.
: ** .PARAMETERS
: ** a, integer that tells function what to do
: ** b, character that tells function what not to do
: ** .RETURN
: ** OK or ERROR
: */
:
: int get-stuff(a,b)
: int a;
: char b;
: ...
:
:
: Which would produce something like
:
: <FF>
: Function:
: get-stuff
:
: Does really nifty things really fast
: and you can dance to it.
:
: Parameters:
:
: a -- an integer that tells function what to do
:
: etc.
:
: It doesn't have be very sophisticated, tangle/web/weave or info-tex are
: really overkill for my purposes. I'm just looking for something where
: the small discipline of documenting important functions correctly
: provides the large benefit of printable basic documentation.
YIKES!!!
This is exactly the sort of thing that Perl was written for in the first
place. At the end you'll find a script that from your sample produces this
output:
Function:
get-stuff
Does really nifty things really fast and you can dance to it.
Parameters:
a, integer that tells function what to do
b, character that tells function what not to do
Returns:
OK or ERROR
You can arrange to have form feeds before each one, or just one per page
if you like. The line "Does really nifty things" is done in fill mode, so
it will reformat the text for you. On the other hand, the lines of
PARAMETERS are preserved intact, with only the indentation changed.
Note that it's assuming the comment structure you used--if wanted something
else you'd have to change the .. patterns.
Larry Wall
lwall@jpl-devvax.jpl.nasa.gov
#!/bin/sh
: make a subdirectory, cd to it, and run this through sh.
echo 'If this kit is complete, "End of kit" will echo at the end'
echo Extracting xcom
sed >xcom <<'!STUFFY!FUNK!' -e 's/X//'
X#!/usr/bin/perl
X
Xwhile (<>) {
X if (m!^/\*! .. m!^\*/!) { # for the lines of the comment
X s/^\*\*\s*//; # discard leading cruft
X $heading = $1 if s/^\.(\w+)\s*//; # possibly switch headings
X eval "\$X$heading .= \$_" if $heading; # append to current heading
X }
X elsif ($XFUNCTION ne '') { # found one of our comments
X $XPURPOSE =~ s/\n/ /g; # so filled lines work right
X @XPARAMETERS = split(/\n/,$XPARAMETERS);
X $XFUNCTION =~ s/\(\)//;
X write;
X reset 'X'; # null out all headings
X $heading = '';
X }
X}
X
Xformat STDOUT =
XFunction:
X @<<<<<<<<<<<<<<<<<<<<<<<<<<
X $XFUNCTION
X
X~~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
X $XPURPOSE
X
XParameters:
X
X~~ @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
X shift(@XPARAMETERS)
X
XReturns:
X
X @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
X $XRETURN
X.
!STUFFY!FUNK!
echo ""
echo "End of kit"
: I do not append .signature, but someone might mail this.
exit