1.3 Documentation Entries🔗ℹ

In general, documented bindings are shown in a blue box where the bound name is in boldface. For example, documentation for my_contract could appear as follows:

value

def my_constant :: Int

The syntactic category of a binding is shown to the right within the box, and it is shown as “value” in the example above. That syntactic category implies a space for the binding, and it determines how the rest of the entry should be interpreted. In the case of value bindings, documentation is written as the start of a def form. Functions are typically documented using a fun form:

function

fun fib(n :: NonnegInt) :: NonnegInt

When a function supports multiple argument counts in a way that is not easy expressed as optional arguments or repetitions, its documentation may shown as separate fun forms, instead of using multi-case | syntax:

function

fun fib(n :: NonnegInt) :: NonnegInt

function

fun fib(n :: Flonum) :: Flonum

Different documentation forms might even be used for the same binding, since a macro implementation of a binding can make it act in different ways in different contexts. A binding’s various forms are always shown in the same blue box, but a single blue box may document multiple bindings.

1.3.1 Documenting Syntactic Forms🔗ℹ

Syntactic forms, such as in the “expression” and “definition” categories, are documented with a grammar template, where non-italicized portions are literal (including the documented binding in boldface), and italicized portions are metavariables. Metavariables stand for syntax that matched a separately defined grammar. A metavariable may be hyperlinked to its definition, like bind below, or it may have a locally defined grammar, such as peano_num below.

definition

def_peano bind = peano_num

peano_num  =  0  |  peano_num + 1

A grammar like the one for peano_num describes syntactic sequences, not values. So, 0, 0 + 1, and 0 + 1 + 1 fit the grammar for peano_num, but 2 does not.

When a syntactic form is an operator, then precedence or an operator order for the operator is shown by keywords such as ~order, ~weaker_than, or ~stronger_than, as in a macro form. Unless otherwise documented, a prefix operator’s precedence corresponds to ~stronger_than: ~other.

1.3.2 Documenting Methods🔗ℹ

When a binding is documented with method, it corresponds to a function that is reachable both through a dotted name and by using . after an object expression. For example, if a Fish.swim method can be called as Fish.swim or as f.swim where f produces a Fish object, it would be documented as follows:

method

method (obj :: Fish).swim(distance :: Real)

Sometimes, the object that a method accepts is different from the namespace where the method is bound. For example, Fish.swim might actually accept any object that satisfies FishOrWhale and works with f.swim where f produces a value that satisfies FishOrWhale. In that case, it would be document as follows:

method

method Fish.swim(obj :: FishOrWhale, distance :: Real)

Note that if this description of Fish.swim started with fun instead of method, it would describe a function that works when called as Fish.swim, but not via f.swim.

In this fun-like form of method, the dotted name’s prefix will always correspond to a class or annotation. The annotation of the first argument can be more permissive, as in the above example, since FishOrWhale presumably accepts any value that satisfies Fish. The argument annotation can also be more constrained, however, as in the following example (assuming that only some Fish objects satisfy FastFish):

method

method Fish.escape(obj :: FastFish)

When a method’s first argument has a more constraining annotation than the one that is a prefix of the method’s name, then objects satisfying the prefix annotation can be used to access the method, even when they do not satisfy the argument annotation. Calling the method through such an object will result in an annotation-satisfaction exception, however.

1.3.3 Namespaces and Modules🔗ℹ

A documented binding may reside in a namespace whose members are typically accessed through a dotted name. Accessing a class method though a dotted name like Fish.swim is an example, and a class acts as a namespace that may export other, non-method bindings. Unlike a class such as Fish, a non-class namespace typically does not have its own documentation; instead, the namespace is implicit in the documentation of its members.

The documentation for a namespace member has the namespace in boldface as part of the documentation entry, as in the following example where the namespace pet_store exports buy and sell:

function

fun pet_store.buy(pets :: List, n :: Number) :: Void

function

fun pet_store.sell() :: Number

When bindings are imported from a module using import, then unless the module’s exports are exposed via open or expose, imported names are accessed using a prefix that is derived from the module name or made explicit with as. Modules are impractical to use without open, often because they provide operators or macros. In other cases, documentation can encourage the use of an intended prefix by showing it as non-boldface in the documentation entry.

For example, fill and drain exports of a module named liquid/water might be documented as follows, showing a non-boldface water prefix on the boldface fill and drain names:

function

fun water.fill() :: Void

function

fun water.drain() :: Number

1.3.4 Classes and Fields🔗ℹ

In the documentation for a class, field names of the class are shown as italic boldface because they serve as representatives for both the default constructor’s arguments (where arguments are shown as metavariabales in italic) and field-accessor functions (where defined names are shown as boldface).

For example, a class Lure with fields weight and color that can be access via Lure.weight and Lure.color would be documented as follows:

class

class Lure(weight :: Number,            color :: String)