Re: DOCUMENTATION (yes, this is shouted)

["Kenneth W. Sodemann" <stuffel pcii net>]

In a previous message, KC5TJA wrote:
> 
> 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 lack of documentation certainly does seem to be quite a problem, 
doesn't it?  This is a problem in software in general (IMHO).  The code 
either seems to be over commented where the writer is basically documenting
the language (telling my stuff I should be able to figure out from the
code), or there are no comments at all.  It appears that the happy
medium is on vacation.

BTW, I really like your example below.  If all libraries were commented
this well, people actually could know what was going on by reading the
headers (unlike now).

> 
> 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
>  * 
>  ************************************************************************/
>