Argument declaration style (Was: ANSI C prototypes)

[Rahul Dhesi]

The way I do it is to begin the comment preceding a function
declaration with the sequence /*@F rather than just /*.  Then I use a
perl script (attached) to summarize all functions and their preceding
comments.  (Strip trailing .signature before use.)  It may not work
if you don't use my style, which is:

     /*@F Here's a nice little function that doesn't do very much, but
     on Usenet, who cares? */

     int myfunc(a, b, c);
     int a;
     char *b;
     long c;
     {
       .. function body here

Perl script follows.

#! /where/to/find/perl
# scan file(s) and extract out function headers and comments
# 1990/06/28 R. D.
# Each C function in a file should begin with:
#     /*@F
## Rahul Dhesi <dhesi%cirrusl at oliveb.ATC.olivetti.com>
## UUCP:  oliveb!cirrusl!dhesi

# When invoked on a C source file (or standard input), this perl
# script prints all functions found.  The output format is:
# a dashed line with the function name; the comments preceding
# the function declaration; and the function declaration.
# The following string, if it begins a comment about a function,
# is not printed:
#    @F

while (<>) {
   if ($inheader) {			# in header;  look for header end 
      if (m"^\s*{")  # match }          #  found end;  print and reset
      {
	 $inheader = 0;
	 if (! $funcname) {
	    $funcname = "UNKNOWN FUNCTION";
	 }
	 printf "\n--- %s ---\n", $funcname;
	 print $descr;
	 $descr = "";
	 $funcname = "";
      } else {						# not found end
	 #s:/\*@F:/*:;
	 # if (!(/\/\*@F\*\// || /\/\*--\*\//))
	 $descr .= $_;					#   collect line
	 if (/^.*\s+(\S+)\s*\([^;]*/ || /^\s*(\S+)\s*\([^;]*/) { 
	    $funcname = $1;   				#   and function name
	    $funcname =~ s/\*//;			#   (delete leading *)
	 }
      }
   } else {				# not in header;  look for one
      if (m"^\s*/\*\@F") {
	 s:/\*@F:/*:;
	 if (! m"^\s*\/\*\*\/\s*$") {
	    $inheader = 1;
	    $descr = $_;
	 }
      }
   }
}
--
Rahul Dhesi <dhesi%cirrusl at oliveb.ATC.olivetti.com>
UUCP:  oliveb!cirrusl!dhesi