PICO-8 Wiki
Advertisement

Use this template at the top of every API reference page.

Here is an example, taken from the ord() page:


{{ApiReference
|name=ord
|shortdesc=Gets the ordinal (numeric) version of a character in a string.
|str||The string whose character is to be converted to an ordinal.
|index|optional|The index of the character in the string. Default is 1, the first character.
|result=The ordinal value of the character at <var>index</var> in <var>str</var>
}}

name=... is the name of the function.

shortdesc=... is a short description, where the first sentence is a verb phrase with an implied noun (e.g. "Draws a sprite, or sprite range, on the screen."), followed by an optional second (full) sentence.

Unnamed template parameters are used in sets of three to describe the function's arguments. The first in each set of three is the name of the argument, the second is blank if the argument is mandatory, or "optional" if it is optional, and the third is a short description of the argument.

result=... or results=... creates an additional special entry at the end of the parameter description list labeled "return-value" or "return-values" where said return value(s) can be described. If you reference arguments to the function, prefer to refer to them by name with <var> tags so the relationships between input and output are clear.

This template supports up to 10 function arguments. Extend the template if more are needed.

Style

Function and argument short descriptions should begin with a capital letter and end with a period. Try to write formally, with a neutral, passive voice.

Avoid using parenthetical notes to describe default values for optional arguments. Using a follow-up sentence allows more flexibility. For instance, the color argument to cls():

Avoid:

|color|optional|A color to use for the background (default=0).

Prefer:

|color|optional|A color to use for the background. The default is 0 (black).
{{{name}}}( )
{{{shortdesc}}}
Advertisement