Document and Usage Conventions

From OpenEUO
Revision as of 09:12, 2 November 2010 by Ximan (Talk | contribs)

Jump to: navigation, search

Documenting Method Calls

In documenting library calls, the following conventions regarding syntax are followed. Indented text in the Call subsection of a method's Calling Convention section describes the method's primary pattern of invocation. For example, for the try library method, the following appears:

Call

local r[,...] = sl.try(func,hndlr)

In this pattern, sl is presumed to have been previously set to the simplelib library interface (see including simplelib for more information on obtaining the interface table). Thus try is a top level member of the library interface and it accepts exactly two arguments, whose types (and possibly other information) are described in the Args subsection:

Args

func is a function
hndlr is a function

The call returns an indefinite number (zero or more) of values of dynamic type, as described in the Results subsection:

Results

r0...rN   results returned from func
or
r0...rN   results returned from hndlr, if func raises an error

An Example Usage section with example code may be present to help clarify actual usage of a method in context. Complex arguments and results are further elucidated in the Description section. Anticipated runtime error conditions are described in the Upon Error section. If a library method's parameters are strictly type checked, it will be noted here. For calls with alternative calling conventions, a final section deals with these cases.