OccamDoc

Introduction

This document describes a standard format for comments in occam-pi source code that can be used to automatically generate API documentation.

Peter Maley produced the original version of this specification -- OccamDoc 3 -- as a student project in 2003. The original inspiration was the JavaDoc specification.

Free text

Free text (notated <text> in this document) consists of plain ASCII text with limited markup. Since OccamDoc may be used to generate output in a variety of formats, no guarantees can be made about how these tags will be rendered in the output; for example, printed manuals may render links as a list of references at the end of the document, and online help may not distinguish between regular, code and emphasised text.

Whitespace is irrelevant, with the exception that a blank line indicates a paragraph break; text will be reflowed as appropriate for the output medium. Some simple tags are provided for semantic markup; these may not be nested.

Example:

--* Draw a straight line between two points using pixels.
-- This uses [@link http://example.com/bresenham/ Bresenham's
-- algorithm] with some adjustments for anti-aliased output.
-- To enable anti-aliasing, pass [@code TRUE] as the [@code antialias]
-- argument.
--
-- Lines may be drawn in the following colours:
-- [@item] red
-- [@item] green
-- [@item] blue
--
-- Note that this code is [@em very] inefficient on vector displays;
-- it is better to use [@ref draw.vector.line].

@code

[@code <text>]

Format text as occam-pi program code (so this may be syntax-highlighted in the output).

@link

[@link <uri> <text>]

Link text to a given URI. The URI must be absolute, and may not contain whitespace characters.

@ref

[@ref <identifier>]

Link to the definition of the given identifier. (Once occam-pi gets a namespace mechanism, the identifier may be qualified with the namespace.)

@em

[@em <text>]

Emphasise the given text.

@text

[@text <text>]

Format text as non-code plain text (for example, sample input or output to a program).

@item

[@item]

Start an unordered list item. The item will extend until either the next @item tag or the end of the paragraph, whichever comes sooner. Adjacent items will be turned into an unordered list in the output.

Basic comment syntax

OccamDoc comments describe an occam-pi declaration of a single identifier. (It would be legal to attach an OccamDoc comment to INT x:, but not to INT x, y:.)

OccamDoc comments start with the string --*, and extend until the next line that does not start with -- (i.e. the next non-comment line). Comments are horizontally aligned with the occam-pi declaration they are describing. Alternatively, single-line comments may be given on the same line as the declaration they are describing.

Comments include a text description of the declaration, followed by a number of tags which describe particular attributes of the declaration. The first sentence of the description will be used as a short description of the declaration in index listings; the first sentence is considered to end at the first instance of the string "", or at the end of the first paragraph, whichever comes sooner.

Tags must start at the beginning of a line, and extend until the start of the next tag declaration or the end of the comment block (and may thus be split across multiple lines). Tags take zero or more arguments.

--* <text>
-- (@<tag> <args>*)*
<declaration>

General tags

The following tags are permitted in any OccamDoc comment.

@deprecated

-- @deprecated

This declaration is deprecated, and should not be used in new code.

@maintainer

-- @maintainer <text>

Specify contact details for the maintainer of the declaration. Typically this will be an RFC2822 email address:

-- @maintainer Joe Emailful <emailful@example.com>

@private

-- @private

The declaration is only for internal use; it should not be shown in API documentation intended for users.

@since

-- @since <text>

This declaration has been available since the given date or version of the software.

PROC, PROC TYPE and FUNCTION declarations

The following tags are permitted on PROC, PROC TYPE and FUNCTION declarations.

Examples:

--* Output a string (with optional padding) to a channel.
-- @param string The string to output.
-- @param width The width, in characters, to pad the output to; if the
--   string is shorter than this, spaces will be added at the end so
--   that width characters are written. Use 0 for no padding.
-- @param out The channel to output to.
PROC out.string (VAL []BYTE string, VAL INT width, CHAN BYTE out!)
  ...  body
:

--* Movable cell type.
-- This should be used for cells which may be moved around the simulation.
-- @param in Commands for the cell
-- @param out The cell's temperature reports, in Kelvin
PROC TYPE CELL.PT IS (CHAN CELL.CONTROL in?, CHAN REAL32 out!):

--* Calculate the length of a UTF-8 string in runes.
-- Runes are Unicode characters, which may be encoded using multiple
-- bytes.
-- @param string The string.
-- @return The number of runes in the string.
INT FUNCTION utf.length (VAL []BYTE string)
  ...  body
:

--* Sort a pair of numbers.
-- @param a, b Input values
-- @return Whether the numbers were already sorted
-- @returns -, - The values in sorted order
BOOL, INT, INT FUNCTION sort.pair (VAL INT a, b)
  ...  body
:

@param

-- @param <identifiers> <text>

Describe one or more formal parameters. To document multiple parameters (which must be of the same type), separate them with commas and optional whitespace.

@return

-- @return <text>

(FUNCTION only.) Describe a return value of the function. Each @return tag describes a single return value.

@returns

-- @returns <identifiers> <text>

(FUNCTION only.) Describe one or more return values of the function. "Dummy" identifiers are used to indicate how many values the text describes; these may be specified as - if you don't want to give them names. To document multiple return values (which must be of the same type), separate them with commas and optional whitespace.

PROTOCOL declarations

The following tags are permitted on sequential PROTOCOL declarations, or on individual tags of a tagged PROTOCOL.

Examples:

--* Graphics to be rendered.
-- @item x X coordinate.
-- @item y Y coordinate.
-- @item pixels Pixel data in packed 24-bit format.
PROTOCOL GRAPHICS IS INT; INT; MOBILE []BYTE:

--* Commands to the rendering engine.
PROTOCOL COMMANDS
  CASE
    --* Start rendering.
    -- @item seed Initial seed for the RNG.
    start; INT
    --* Stop rendering.
    stop
:

@item

-- @item <identifiers> <text>

Describe one or more items of the protocol. As with @returns, the identifiers may be chosen by the programmer (since occam-pi protocol declarations do not take identifiers), or may be given as -. If multiple identifiers are given, they must all be of the same type. Counted arrays count as one item.

RECORD and CHAN TYPE declarations

No extra tags are permitted on RECORD or CHAN TYPE declarations, but OccamDoc comments may be used on individual fields of a record; for example:

--* A chunk of image data.
DATA TYPE CHUNK
  MOBILE RECORD
    INT x:               --* X coordinate.
    INT y:               --* Y coordinate.
    MOBILE []INT pixels: --* Pixel data in packed 24-bit format.
:

--* Two-way link to an oracle process.
CHAN TYPE ORACLE.LINK
  MOBILE RECORD
    CHAN INT req?:  --* Requests
    CHAN INT resp!: --* Responses
:

Other declarations

No extra tags are permitted on declarations of constants, variables, abbreviations, timers, ports, or non-record data types.

Example:

--* Width of display.
VAL INT WIDTH IS 640:

Header comments

A single header comment may be supplied in a file to provide information about the file itself. Header comments follow the same format as regular OccamDoc comments, but start with --** and do not have an associated declaration.

--** <text>
-- (@<tag> <args>*)*

The following additional tags are permitted in header comments.

Example:

--** Fast maths library.
-- This library provides maths functions which have good performance
-- but only limited accuracy.
--
-- @module fastmath
-- @maintainer Joe Math <math@example.com>

@module

-- @module <identifier>

Give the module that this source file is part of. Modules are collections of related code such as reusable libraries; the documentation for all the declarations in a module will be grouped together. If no @module tag is given, the module name is assumed to be the same as the source filename.

For each module, there should be one source file with a full header comment in; additional source files should only specify that they're part of the module:

--** @module fastmath

Groups

Group comments may be used to gather a group of related constants together. A group starts with --* followed by one or more {s, the common prefix for the constants in the group, and a regular comment block, and ends with --* followed by one or more }s.

--*({)+ <prefix> <text>
-- (@<tag> <args>*)*
<code>
--*(})+

Example:

--*{ DIRECTION Direction specifiers for window gravity.

--* Top of screen.
-- This excludes the menu bar on platforms where it is fixed.
-- (Note the blank line to separate this comment from the start of the group.)
VAL INT DIRECTION.NORTH IS 0:
VAL INT DIRECTION.SOUTH IS 0: --* Bottom of screen.
VAL INT DIRECTION.WEST IS 0: --* Left of screen.
VAL INT DIRECTION.EAST IS 0: --* Right of screen.
--*}

Groups are only necessary because occam-pi does not yet have support for enumerated types; when this is added to the language, groups may be removed from OccamDoc.

OccamDoc (last edited 2007-06-13 00:43:46 by ats1)