Function Documentation Conventions

A typical function definition looks like

(strcat string string -> string )
File: job.t
Status: alpha

The strcat function concatenates two strings and returns the resulting string.

The first line gives the name of the function followed by the the number of values it accepts and returns, separated by ->. There may be more than one line like this if the function does several distinct tasks depending on the types of its parameters. Groups of related functions may also be listed one per line here. Operators other than functions (such as function definition, variable assignment, and control structure operators) give a synoptic usage example rather than a simple argsIn/argsOut declaration.

The second line gives the source file implementing the function.

The third line will be one of:

`Status: temporary'

This function is needed at the moment but is scheduled to be replaced by something better. releases.

`Status: tentative'

The function is offered for discussion and perhaps experimentation, but is very likely to change in future releases.

`Status: alpha'

The function is in useful form, but is subject to change if any possible improvement becomes evident.

`Status: beta'

The function is thought to be final form, but is subject to change if significant problems are identified in actual use.

`Status: production'

The function is baselined for general use, and incompatible changes will be made only as a last resort. (Compatible extensions, such as allowing additional argument types, may still be considered.)

Go to the first, previous, next, last section, table of contents.