Walnut

Documentation

In-source documentation

Walnut documentation lives in the source. Module and value comments drive the API site; the compiler fills in types; fenced examples can run as doctests.

Authoring

Module docs — immediately after module … exposing …:

module Test exposing
    ( Expectation
    , test, describe, run, format
    )

{-| Suites for the host JIT.

# Expectations
@docs Expectation, equal, equalInt

# Suites
@docs test, describe
-}

Value / type docs — immediately above the declaration:

{-| Compare integers. Prefer this over `equal` for ints.

    equalInt 1 1
    --> Pass
-}
equalInt : Int -> Int -> Expectation

(Or use a fenced walnut code block with a --> expected line — both forms are doctests.)

Conventions:

RuleDetail
`{-`
{- / --Implementation comments (still discarded)
@docs A, BMust start at column 0 of its line inside the comment
Fenced walnutDoctest when a --> expected line is present
@since / @deprecatedOptional tags

Compiler types are injected into the catalog — you do not retype signatures for the site.

Commands

walnut docs              # validate + write docs/api/
walnut docs --strict     # fail on @docs mistakes (also runs doctests)
walnut docs --doctest    # run fenced examples on the host JIT
walnut docs serve        # generate + local preview server
walnut docs --json out.json

walnut docs --stdlib writes the API site (Homebrew: share/doc/walnut/api/).

--strict fails if any module is missing a module {-| comment, if @docs is wrong, or if an exposed name lacks a value doc. All toolchain stdlib modules (Ui, Test, Cmd, Sub, Walnut, effects, …) are documented.

Site

Generated HTML + CSS + JS + data/docs.json — no Node required. Features:

  • Module index with one-line summaries
  • Sticky nav + on-page jump links from @docs sections
  • Client-side fuzzy search (names + comments)
  • Copy signature, dark/light theme

Open docs/api/index.html after generating.

Doctests

Fenced examples with --> run as doctests on the host (same path as walnut test). Expression-only for v1.

Editor

LSP hover shows the signature plus the same Markdown prose as the site.

Formatter

When @docs order parses cleanly, walnut format reorders exposing (…) to match.

See also