Difference between revisions of "Document and Usage Conventions"
m |
m |
||
| Line 21: | Line 21: | ||
An Example Usage section with example code may be present to help clarify actual usage of a method in context. | 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. | 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. | ||
| + | |||
| + | == See Also == | ||
* [http://www.easyuo.com/openeuo/wiki/index.php/Simplelib simplelib] | * [http://www.easyuo.com/openeuo/wiki/index.php/Simplelib simplelib] | ||
* [[try]] | * [[try]] | ||
Revision as of 08:13, 2 November 2010
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.
