#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:
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:
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:
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.