GRDOC

All files should start with a grdoc header, and all functions should have grdoc headers.

The file grdoc should contain a description of the contents of the file and a version with the CVS $Header$ tag.

The function grdoc should contain

• a description of the function, saying what it does.
• the functions called by this function.
• all function arguments with descriptions of what they are and what they are used for.
• the return codes should be described.

Note that the `calledby' field should not be filled in as this is unmaintainable.

The standard grdoc function header is of the form

 /*@@
   @routine    Template
   @date       Fri Oct  6 10:51:49 2000
   @author     Tom Goodale
   @desc
   An example of grdoc
   @enddesc
   @calls     templatefunc2
   @calledby
   @history

   @endhistory
   @var     templatestring
   @vdesc   string describing foobar
   @vtype   const char *
   @vio     in
   @vcomment

   @endvar

   @returntype int *
   @returndesc
   0 - success
   or the returncode of @seeroutine templatefunc2
   @endreturndesc
@@*/

This is the form which will be created if you use the grdoc emacs mode. The variable descriptions and the return code decription should be placed after the history so that they are close to the actual function.

After the first actual release the history should be filled in with each change.