Update Verona Language Documentation

Update the documentation in vc/docs/ to reflect a new feature or change to the Verona compiler.

Arguments

• $0 — a description of the feature or change that needs documenting (e.g., "callback support", "new builtin type", "new syntax")

Documentation Structure

The docs live in vc/docs/ with 27 numbered chapters plus a README.md table of contents:

Steps

1. Identify which docs need updating

Read the feature description and determine which documentation files are affected. Use this checklist organized by feature type:

New builtin type (e.g., callback, ptr):

• 22-builtin-types.md — Add type section with method table
• 01-getting-started.md — Update _builtin directory listing if new file added
• 03-types.md — If it's a new primitive or special type
• Relevant feature chapter (e.g., 17-ffi.md for FFI-related types)

New _builtin file or subdirectory:

• 01-getting-started.md — Update _builtin directory tree listing
• 02-program-structure.md — If it changes the top-level structure
• 16-modules.md — If it introduces a new namespace (e.g., ffi::)

New syntax (keyword, operator, construct):

• 23-grammar-summary.md — Add or modify grammar production rules
• Relevant feature chapter for usage documentation
• 05-expressions.md — If it's a new expression form
• 06-control-flow.md — If it's a new control flow construct

New FFI feature:

• 17-ffi.md — Primary documentation (add new section)
• 22-builtin-types.md — If new builtin types/functions are exposed
• 17-ffi.md table of builtin categories — Add rows for new builtins
• 15-concurrency.md FAQ — If it affects scheduling/external resources
• 27-common-patterns.md — Add usage pattern

New compiler pass or pass change:

• 20-compiler-pipeline.md — Update pass table or descriptions

New CLI option:

• 21-toolchain-usage.md — Add option documentation

2. Read the source of truth

Before writing documentation, read the actual implementation to ensure accuracy:

• _builtin files: vc/_builtin/ — Verona source defining types and methods
• FFI builtins: vc/_builtin/ffi/ — FFI wrapper functions
• Builtin categories table: vc/passes/dot.cc — The builtins map defines all ::: builtins
• Grammar: vc/passes/parse.cc for tokenization, vc/passes/structure.cc for AST structure
• WF definitions: vc/lang.h for frontend WF, include/vbcc.h for backend WF
• Interpreter behavior: vbci/thread.cc for runtime semantics

3. Write the documentation

Follow these conventions:

Section numbering:

• Sections use ## N.M Title format where N is the chapter number
• When adding sections at the end, use the next available number
• When inserting sections, renumber subsequent sections and update all internal cross-references

Cross-references:

• Format: [Title §N.M](filename.md) for section references
• Format: [Title](filename.md) for chapter references
• Chapter headers have navigation links: [← Table of Contents](README.md) | [Previous: Title](prev.md) | [Next: Title →](next.md)

Code examples:

• Use ```verona fenced blocks for Verona source code
• Use ```bash for shell commands
• Use ```cpp for C/C++ code (e.g., in FFI examples)
• Examples should be self-contained and runnable where possible
• Follow idiomatic Verona style (see CLAUDE.md "Idiomatic Verona style")

Method/API tables:

• Use | Method | Signature | Description | format
• Include all public methods for builtin types
• Group related methods logically

Tone and style:

• Direct and technical — written for programmers
• Explain "why" for non-obvious design decisions
• Use "See Chapter" for cross-references rather than repeating content
• Mark unimplemented/planned features with > **Status:** Not yet implemented.

4. Verify cross-references

After writing, check that:

• All [text](file.md) links point to files that exist
• Section numbers referenced in cross-links (§N.M) match actual section numbers
• No dangling references to renamed/renumbered sections
• The README.md table of contents is still accurate

5. Check for ripple effects

A documentation change in one file often requires updates in others:

• Adding a section to 17-ffi.md may need a cross-reference from 22-builtin-types.md
• New syntax in 23-grammar-summary.md should be explained in the relevant feature chapter
• New patterns in 27-common-patterns.md should cross-reference the feature chapter
• New gotchas in 26-gotchas.md should cross-reference relevant chapters
• If you renumber sections, search all docs for §old_number references to update

6. Report

State which files were updated, what sections were added/modified, and any cross-references that were created or updated.

Common Patterns for Specific Feature Types

Documenting a new _builtin/ffi/ wrapper

1. Add function to the table in 17-ffi.md §17.8 "Available Wrappers"
2. Add function signature to 22-builtin-types.md §22.13 "FFI Module Functions"
3. Add usage example in the relevant 17-ffi.md subsection
4. If it introduces a new concept, add a pattern to 27-common-patterns.md

Documenting a new ::: builtin

1. Add row to the builtin categories table in 17-ffi.md §17.3
2. Document the semantics in the relevant feature section
3. If user-facing (not just compiler-internal), add to 22-builtin-types.md

Documenting a new class in _builtin

1. Add to 01-getting-started.md _builtin directory listing (alphabetical order)
2. Add full type section to 22-builtin-types.md with:
   • Brief description
   • Method table (Method | Signature | Description)
   • Code example
   • Cross-references to related chapters
3. If it's a primitive numeric type, add to 03-types.md tables