Skip to content
Weaverv0.5.0

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.

// 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.

/// 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
}

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.
#Error
pub 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 parameter
temperature.wft:39:5: the doc of `scaleOf` names `Missing` in `# Errors`, which is not a variant of UnitError, its error type

A 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.

The blocks of an # Examples section are compiled and run by wv test, beside the tests, each named after what it documents:

Terminal window
wv test
ok a kelvin is no scale (0.00 s)
ok doc of convert, example 1 (0.00 s)
2 test(s), all passed

An 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.

wv doc writes the documentation of the pub declarations of a program or a library, and checks its sections on the way:

Terminal window
wv doc -format html -o doc-html . # a page per module, and an index
wv doc -format markdown -o doc-md .
wv doc -format json -o doc.json . # the model other tools read
wv doc weaver.fs # the standard library's

Each 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.md opens 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, and module: when it belongs to another module than the package’s root:
---
title: Converting temperatures
order: 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.