Re: [gtk-list] DOCUMENTATION (yes, this is shouted)

[KC5TJA <kc5tja topaz axisinternet com>]

On Fri, 21 Aug 1998, Juergen A. Erhard wrote:

> Now, am I the only programmer who sometimes puts some comments in his
> code?  The gtkprogress.c, for example, sports exactly 5(!) comments.
> And this is counting the copyright header and one comment that
> consists of a row of '*'.

Well said.  However, I recommend using a commenting style that lends
itself to self-extraction by a documentation tool.  For instance, in my
home-brew OS that I'm writing, I have this function.  My entire API is
documented in this way.

The only thing I need to do now is port Amiga's "autodoc" to Linux.  :-)

/****** ResidentScan *****************************************************
 * 
 * NAME
 * 	ResidentScan
 * 
 * SYNOPSIS
 *    	resident = ResidentScan( rsc );
 * 
 * 	Resident *resident;
 * 	ResidentScanContext *rsc;
 * 
 * FUNCTION
 * 	Scans a region of memory, determined by `rsc', for a Resident
 * 	structure.
 * 
 * INPUTS
 * 	rsc	Pointer to an initialized ResidentScanContext structure.
 * 		This structure must be initialized as follows:
 * 
 * 		firstByte	Pointer to start of scan region
 * 		nextByte	Initially the same as firstByte
 * 		lastByte        Pointer to the end of the scan region
 * 		residentsFound  Set to zero.
 * 
 * RESULT
 * 	NULL if no (more) residents were found.  Otherwise, a pointer to
 * 	the Resident structure is returned.
 * 
 * 	The supplied ResidentScanContext structure is modified in place.
 * 	As scanning progresses, nextByte always points to the next byte
 * 	to start scanning from.
 * 
 *      residentsFound is automatically incremented everytime this function
 * 	finds a resident.
 * 
 * BUGS
 * 
 * SEE ALSO
 * 	LibraryNewFromResident
 * 
 ************************************************************************/

Resident *ResidentScan( ResidentScanContext *rsc )
{
   ... function body clipped ...
}

==========================================================================
      KC5TJA/6     |                  -| TEAM DOLPHIN |-
        DM13       |                  Samuel A. Falvo II
    QRP-L #1447    |          http://www.dolphin.openprojects.net
   Oceanside, CA   |......................................................