Looking for simple docuemtation extractor

[Larry Wall]

In article <DGA#'-*@rpi.edu> krf at 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 at 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