Comments and documentation
Weaver has two kinds of comments. // is for whoever reads the code, and
/// documents a declaration for whoever uses it. The compiler checks
documentation like code: a doc that names a parameter the function does
not have, or an example that no longer compiles, is an error.
Comments
Section titled “Comments”// runs to the end of the line. There are no block comments.
// Temperatures and their scales. A file's opening comment is for its// maintainers: the generated documentation leaves it out.
fn clamp(x: Int): Int { // The sensor reports -1 when it is unplugged: count it as zero. return x.max(0)}A comment says why. What the code does, the code already says.
Doc comments
Section titled “Doc comments”/// documents the declaration that follows it: a type, a field, a
variant, a function, a contract. Its text is Markdown, which the editor
shows on hover and wv doc publishes. Meta code reads it too: the help of a
#Cli command line is the /// of its fields.
/// A temperature scale.pub enum Scale = Celsius | Fahrenheit
/// A reading of a sensor.pub type Reading = { /// The temperature, in the scale `scale`. pub degrees: Float pub scale: Scale}Sections the compiler checks
Section titled “Sections the compiler checks”A function’s doc can carry sections, under fixed English headings:
| Section | Holds |
|---|---|
# Parameters |
a list, each entry starting with a parameter’s name in backticks |
# Returns |
what the function returns, in free text |
# Errors |
a list, each entry naming a variant of the function’s error type |
# Panics |
when the function stops the program |
# Examples |
weaver code blocks, which are tests |
Here is a small library documented that way:
import weaver.test.assert
/// A temperature scale.pub enum Scale = Celsius | Fahrenheit
/// Why a unit cannot be read.#Errorpub enum UnitError = | Empty `error("no unit")` | Unknown(unit: String) `error("unknown scale '${unit}'")`
/// Converts degrees from one scale to another.////// # Parameters/// - `degrees`: the temperature, in the scale `from`./// - `to`: the scale of the result.////// # Returns/// The same temperature in the scale `to`.////// # Examples/// ```weaver/// assert(convert(100.0, from: .Celsius, to: .Fahrenheit) == 212.0, "water boils")/// ```pub fn convert(degrees: Float, from: Scale, to: Scale): Float = match (from, to) { (Celsius, Fahrenheit) => degrees * 9.0 / 5.0 + 32.0 (Fahrenheit, Celsius) => (degrees - 32.0) * 5.0 / 9.0 _ => degrees}
/// Reads the scale of a unit, `C` or `F`.////// # Errors/// - `Empty`: the unit is empty./// - `Unknown`: the unit names no scale.pub fn scaleOf(unit: String): Scale ! UnitError = match unit { "" => fail Empty "C" => Celsius "F" => Fahrenheit _ => fail Unknown(unit)}
@test("a kelvin is no scale")fn rejectsKelvin() { assert(scaleOf("K") is Err(Unknown(_)), "K is not a scale here")}The sections stay true as the code changes. Rename the parameter to, or
the variant Unknown, and the build stops on the doc that still names
them:
temperature.wft:28:5: the doc of `convert` names `target` in `# Parameters`, but `convert` has no such parametertemperature.wft:39:5: the doc of `scaleOf` names `Missing` in `# Errors`, which is not a variant of UnitError, its error typeA parameter may be left out of # Parameters. Any other top-level
heading in a function’s doc is a warning; lower-level ones are free.
Examples are tests
Section titled “Examples are tests”The blocks of an # Examples section are compiled and run by wv test,
beside the tests, each named after what it documents:
wv testok a kelvin is no scale (0.00 s)ok doc of convert, example 1 (0.00 s)2 test(s), all passedAn example is the body of a function: it sees the module’s names and the
file’s imports, assert and assertEq without importing them, and it may
fail with !. An example that cannot run as a test, one that reaches the
network or serves forever, goes in a code block outside # Examples.
Generating the documentation
Section titled “Generating the documentation”wv doc writes the documentation of the pub declarations of a program
or a library, and checks its sections on the way:
wv doc -format html -o doc-html . # a page per module, and an indexwv doc -format markdown -o doc-md .wv doc -format json -o doc.json . # the model other tools readwv doc weaver.fs # the standard library'sEach declaration gets its signature, its doc and its sections, a type its
fields, variants and methods, and the contracts it adopts. -all includes
what is not pub.
A package’s prose goes along:
- its
README.mdopens the index; - the Markdown files of its
doc/folder are pages, shown before the items of their module. A page may start with a front matter that sets its title and its rank, andmodule:when it belongs to another module than the package’s root:
---title: Converting temperaturesorder: 1---
`convert` takes the scale of its input and of its output.wv publish sends that documentation with the package, and the
registry shows it on the package’s page.
The guides on this site are the doc/ pages of the
standard library.