Doc Forms (Typed Comments)

The Fold uses (doc ...) forms for searchable, introspectable annotations that survive in source code.

Basic Syntax

Contextual (belongs to enclosing definition)

scheme
1(define (add x y)
2  (doc 'type (-> Int Int Int))
3  (doc 'description "Adds two numbers")
4  (+ x y))

Targeted (names what it documents)

scheme
1(doc factorial 'type (-> Int Int))
2(define (factorial n)
3  (if (= n 0) 1 (* n (factorial (- n 1)))))

Semantics

Standard Tags

Search Commands

After loading lattice/meta/docs.ss:

scheme
1(lf-todo)           ; Find all todos in codebase
2(lf-types)          ; Find all type annotations
3(docs-for 'symbol)  ; Find docs for specific target
4(doc-stats)         ; Count docs by tag

Type Checker Integration

Doc type annotations integrate with both the LSP and type inference:

Example: Declaring Types for Inference

scheme
1;; The type checker will trust this annotation
2(doc my-complex-fn 'type (-> (List Int) (Maybe Int)))
3(define (my-complex-fn lst)
4  ;; Complex implementation...
5  )

Todos vs BBS Issues

Rule of thumb: If it needs to be scheduled or tracked across sessions, use BBS. If it's a note-to-self next to the code, use (doc 'todo ...).

Examples

Full Function Documentation

scheme
1(define (binary-search vec target)
2  (doc 'type (-> (Vector Int) Int (Maybe Int)))
3  (doc 'description "Binary search for target in sorted vector")
4  (doc 'param 'vec "Sorted vector of integers")
5  (doc 'param 'target "Value to find")
6  (doc 'returns "Index wrapped in Just, or Nothing if not found")
7  (doc 'todo "Add bounds checking")
8  ;; implementation...
9  )

Deprecation

scheme
1(doc old-api 'deprecated "Use new-api instead. Will be removed in 2.0")
2(define (old-api x) (new-api x))

Module-Level Documentation

scheme
1;; At top of file
2(doc 'description "Matrix operations for linear algebra")
3(doc 'since "1.0.0")
4(doc 'see 'linalg/vec)