Path: utzoo!attcan!uunet!cs.utexas.edu!swrinde!zaphod.mps.ohio-state.edu!samsung!olivea!tymix!cirrusl!ss108!dhesi
From: dhesi%cirrusl@oliveb.ATC.olivetti.com (Rahul Dhesi)
Newsgroups: comp.lang.c
Subject: Re: Argument declaration style (Was: ANSI C prototypes)
Message-ID: <2678@cirrusl.UUCP>
Date: 12 Nov 90 05:02:01 GMT
References: <1990Nov2.030556.27759@ccu.umanitoba.ca> 	<RJC.90Nov3153129@brodie.uk.ac.ed.cstr> <3933.27353319@cc.helsinki.fi> 	<_1X6_32@xds13.ferranti.com> <3944.27367fb2@cc.helsinki.fi> 	<1990Nov06.233654.29974@dirtydog.ima.isc.com> 	<BZS.90Nov6205843@world.std.com>
Sender: news@cirrusl.UUCP
Organization: Cirrus Logic Inc.
Lines: 68

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@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@oliveb.ATC.olivetti.com>
UUCP:  oliveb!cirrusl!dhesi