#Documentation and Tests

Rig documentation and tests are staged values. They use ordinary source expressions and checked code, with dedicated descriptors that let the tools discover them.

#Documenting a Binding

A documentation binding uses the same name as its subject and describes its exact type:

(define increment:(Fn Int Int) increment=(fn value:Int do=(add value 1)) increment:(Doc_1 (Fn Int Int)) increment=(doc "Returns the input plus one, with wrapping Int arithmetic.")) (provide increment:(Fn Int Int))

The function exists at Stage 0; its Doc_1 descriptor exists at Stage 1. The shared name and exact function type identify the documented binding without making the documentation an ordinary overload.

doc expects Text at the descriptor's stage. Its operand may be a literal, a raw multiline string, or the result of a function that constructs Text.

Read public project documentation with:

rig doc main.rig

Only documentation attached to provided subjects is included. The command also accepts a directory containing main.rig, or no path to use the current directory. It includes local project modules, not dependency-package documentation.

#Writing Tests

A test descriptor carries checked code for a zero-argument function returning Null:

(define increment:(Fn Int Int) increment=(fn value:Int do=(add value 1))) (define increments:Test_1 increments=(test (code (fn do=(assert (eq (increment 41) 42))))))

Test_1 is created at Stage 1 and describes a test that runs at Stage 0. code obtains the expected lower-stage function type from test. The body is checked using its definition-site bindings.

Run project tests with:

rig test main.rig

Tests need not be provided. Registration comes from top-level Test-typed bindings, not a naming convention; local descriptors and descriptors stored in collections are ordinary values rather than additional registered tests.

Normal build and run commands do not evaluate unreferenced documentation or test metadata. rig doc and rig test select the descriptors they need and evaluate their dependencies.

#Assertions

assert evaluates its Bool argument and returns Null. During an observed test invocation, a false assertion records a failure at its source location and execution continues. A test can therefore report more than one failed assertion.

In ordinary, uninstrumented execution, assert still evaluates its argument but does not enforce it. Use explicit precondition checks, Variants, or trap for program behavior that must hold outside tests.

A trap is different from a false assertion. A trap, capability denial, or execution failure may abort the rest of that stage's suite; remaining tests are reported as not run.

#Testing Higher Stages

A descriptor lives one stage above the computation it tests:

(define twice:(Fn_1 Int_1 Int_1) twice=(fn value:Int_1 do=(add value value))) (define doubles_at_compile_time:Test_2 doubles_at_compile_time=(test (code (fn do=(assert (eq (twice 21) 42))))))

This test executes at Stage 1. With no filter, rig test runs tested stages from higher to lower. Select a particular tested stage with:

rig test main.rig --stage 1

Documentation follows the same relationship: Doc_2 documents a Stage 1 subject. Descriptors are compile-time metadata, not values that cross public Component interfaces.

#State and Authority

Tests at one stage execute in source order and share one instance. They are not isolated snapshots. Use fresh local state when independence matters; a test can otherwise affect later tests through shared references.

All test stages, including Stage 0, use the project's compile capability profile. A test does not gain runtime authority merely because it tests runtime code. Descriptor evaluation and nested checking also remain part of compile-time execution.

Use Staging for the Code and capture model, and CLI for command selection and options.