[GAP Forum] standards for documenting GAP source code

[Steve Linton]

Dear GAP Forum,

On Tue, 23 Jan 2007 00:15:04 -0500
Allan Adler <ara at zurich.csail.mit.edu> wrote:

> 
> I've started reading some of the C source code for GAP 3 (yes, I know
> there is a more recent GAP; I'll get to it eventually) and so far I'm
> impressed by the excellence of the commenting of the source code. I'd
> just like to know whether there are any explicitly formalized standards
> that are for documenting the GAP source code. If so, I'd like to read
> them so that I can try to adopt some of them in my own programs.
>

The short answer is no. The source code documentation reflects the
excellent practice of the initial authors of GAP 3, mainly Martin Schoenert,
and was carried into the older parts of GAP 4, but, to my knowledge, was never
codified. Some later additions are less well commented, but we try to follow
the general pattern. 

Some of the commenting in the GAP4 library code (mainly .gd files) is
automatically inserted into the manuals during the build process, so follows
the rules of our manual formats.

	Steve Linton

-- 
Steve Linton	School of Computer Science  &
      Centre for Interdisciplinary Research in Computational Algebra
	     University of St Andrews 	 Tel   +44 (1334) 463269
http://www.cs.st-and.ac.uk/~sal 	 Fax   +44 (1334) 463278