Re: Documentation

[John R Sheets <dusk smsi-roman com>]

Miguel de Icaza wrote:

> /**
>  * function_name:
>  * @par1:  description of parameter 1
>  * @par2:  description of parameter 2
>  *

I think we should add a single file header comment at the top of each file that
allows us to describe the file's functionality as a whole.  We need an executive
summary to draw the docs together, and make them more cohesive/useful/self-aware.
Otherwise we're splintering into an obesely long list of function descriptions.
Maybe something like this:

/**
 * file_name:
 * @purpose:  quick reason for existance
 * @scope:  what areas of GNOME the module affects
 *
 * module description.  A more in-depth discussion of its usage
 * as a whole, general advice, etc.
 */

John