This page serves as an explanation on how to read the function pages on this wiki.
Your typical function page will be composed of three or four sections:
type :function-name ( type $VALUE , … )
type :function-name ( type &REFERENCE )
type :function-name
This is what a typical declaration section looks like. Types, obviously, explain the type of value returned by function and what kind of arguments it takes. In the parentheses follows the list of arguments. A function may be able to take a variable number of arguments, or act differently based on types passed. If there is an ellipsis (…
) in the argument list, it means the function can take any number of arguments.
Variables references are are prefixed with the ampersand symbol (&
) and underlined to further distinguish them from values. A reference in a declaration does not mean, however, that the value absolutely must be a variable reference - it is only a note that passing a reference might modify the variable. On the other hand, using a variable reference where the documentation mentions a value is guaranteed to leave it intact.
There are a few pseudotypes used in this documentation, that is:
This section usually contains information about what the function does and what is the meaning of its arguments. It may also mention how the function performs when passed different value types, or when some of it's arguments are omitted.
This section appears only with some functions, most notably arithmetic and comparison functions, where it explains how the operations are performed when concerning values of different data types. It may also explain how to construct the format string in functions expecting one.
This section will always contain a short example demonstrating the use of a function. Some of these may be just one-liners, whereas some may contain some multi-line script, along with a commentary.
wikipage modified on 2014/0601/2317