Doctests
Doctests keep examples next to the API they describe.
Docstrings
A doc block uses --- before a declaration.
---
Clamp a value.
---
pure func clamp(x: Int) -> Int:
x
Named Doctests
Each doctest can include a readable name after ::.
doctests:
:: clamps low value
clamp(2, 5, 10) == 5
Examples As API Contracts
Doctests are examples that the test runner can execute.
doctests:
:: keeps in-range value
clamp(7, 5, 10) == 7
Running Doctests
blorp check typechecks source but does not execute doctests. Use blorp test --doc on a package or std module when you want only doctests.
blorp test --doc pkg/docs/clamp.brp
blorp test --doc std/string.brp
Example
clamp.brp
---
Clamp x into the inclusive [low, high] range.
doctests:
:: below range
clamp(2, 5, 10) == 5
:: inside range
clamp(7, 5, 10) == 7
:: above range
clamp(20, 5, 10) == 10
---
pure func clamp(x: Int, low: Int, high: Int) -> Int:
if x < low:
low
else if x > high:
high
else:
x
Try it
terminal
blorp test --doc pkg/docs/clamp.brp