Difference between revisions of "Document and Usage Conventions"
m |
m (→Documenting Method Calls) |
||
| Line 1: | Line 1: | ||
== Documenting Method Calls == | == 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: | + | 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 in a form of pseudo code. For example, for the [[try]] library method, the following appears: |
Call | Call | ||
local r[,...] = sl.try(func,hndlr) | local r[,...] = sl.try(func,hndlr) | ||
| − | In this pattern, ''sl'' is presumed to have been previously set to the simplelib library interface (see [http://www.easyuo.com/openeuo/wiki/index.php/Including_simplelib_in_a_Project| 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: | + | In this pattern, ''sl'' is presumed to have been previously set to the simplelib library interface (see [http://www.easyuo.com/openeuo/wiki/index.php/Including_simplelib_in_a_Project| including simplelib] for more information on obtaining the interface table). Thus try is a top level member of the library interface, is called with the dot (.) operator, and it accepts exactly two arguments, whose types (and possibly other information) are described in the Args subsection: |
Args | Args | ||
| Line 20: | Line 20: | ||
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. Instead of promulgating numerous calling conventions for a single function, sometimes the library presents two or more functions with almost identical functionality but with differing invocation. | ||
== See Also == | == See Also == | ||
Latest revision as of 09:20, 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 in a form of pseudo code. 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, is called with the dot (.) operator, 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. Instead of promulgating numerous calling conventions for a single function, sometimes the library presents two or more functions with almost identical functionality but with differing invocation.
