Euphoria Standard Library (ESL) - Commenting Guidelines

Code Commenting Guidelines

Status of this topic : under discussion

The Euphoria Standard Library, like many other large projects, requires that code submitted be properly commented acording to our specifications. Standardized code commenting is necessary because it makes the code easier to read and understand for both the user and the maintainer and it allows us to use programs to generate documentation from the comments.

Each file must start with a section of comments discussing the purpose of the file.
This block should be put before any code at the top of the file.

Comment tag	-	Description of tag
Name:		Name of library/program. Required
Author:		Author's name
Created:		Date file was created
Updated:		Date file was updated
License:		License library's source code is released under
Intro:		Introduction comments about the library

Additionally each routine/comment/type must be commented right before it to describe its behavior, syntax, etc.

Comment tag	-	Description of tag
Routine: Type: Constant:		Name of the routine/type/constant. Required (only use one)
Author:		Author of the routine
Created:		Date routine was created
Updated:		Date routine was updated and contributor who did so
Platform:		Platform the routine runs on (General, WIN32, DOS32, Linux, FreeBSD)
Syntax:		An illustration of the usage syntax
Description:		A description of what the routine does
Comments:		Extra comments about the routine
Example:		A more example to illustrate usage
Example Program:		The name/location of an example program if such a program exists
See Also:		Lists other related routines in the library

For an example please see the example file boolean.e