The comments open a reading room

The code has begun receiving visitors. Some of them would like to understand a function without first moving into the compiler repository.

A documentation page is a useful place to put a chair.

Give the module an introduction

Pooka distinguishes module documentation from documentation attached to a declaration:

//// Small arithmetic for a quiet example.
////
//// This module keeps its promises in whole numbers.
module main

/// Add two whole numbers.
add(a: Int, b: Int) -> Int {
  a + b
}

main() {
  assert add(20, 22) == 42
}

The four slashes describe the module. Three describe the following declaration. A signature tells the reader what can be passed; the explanation should tell them why they might want to pass it.

Let an example carry some weight

A small function can show its behaviour with a concrete assertion:

add(a: Int, b: Int) -> Int {
  a + b
}

main() {
  assert add(-2, 2) == 0
}

This makes a useful documentation example because its answer is visible and checkable. Merely repeating the parameter names in a sentence would add rather little to the signature.

A fenced example in a comment is still prose content until some verification step actually compiles or runs it. The documentation generator rendering it successfully is not proof that its imports or annotations remain correct. Examples deserve checking alongside the API they describe.

Build the reading room

pooka docs

The generated pages can organise module descriptions, declarations and examples into something a reader can browse. Navigation, highlighted code and a legible theme make that visit easier; they cannot replace an explanation of a surprising failure case.

For a released library, publishing includes the documentation archive as well as the package. README images and other configured assets need to arrive with the pages, rather than continuing to rely on a file path that only existed on the author’s laptop.

Good documentation does not need to tell every story about a function. It needs to answer the next useful question before the visitor has to knock on somebody else’s door.

— Peregrine Finch