Re: Documentation

[Scott Wimer <scottw dev cgibuilder com>]

John,

As the monkey who volunteered to strip these things out into documentation,
I think that this is a pretty good idea.  The trick will be making sure that
it's possible to recognize this particular docu-comment block from those that
are specifically for individual API functions.  I'm thinking a slight
modification to the format (as I'll indicate below) will make this easier
for me, without adding any measurable burden on the part of the module
authors.

On Fri, 16 Oct 1998, John R Sheets wrote:

> 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:

How about:
   * @file: file_name
That will make it easy to know more or less imediately that the first 
docu-comment block is actually meant to be attached to the file as a whole,
and not a particular function.  Making this distinction initially makes
my life better. :) 
  regards,
  scottwimer

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

--
Scott Wimer
play  --->    scottw@cgibuilder.com         http://www.cgibuilder.com/
work  --->    scottw@corp.earthlink.net     http://www.earthlink.net/