doc-forms

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)

(define (add x y)
  (doc 'type (-> Int Int Int))
  (doc 'description "Adds two numbers")
  (+ x y))

Targeted (names what it documents)

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

Semantics

Standard Tags

Search Commands

After loading lattice/meta/docs.ss:

(lf-todo)           ; Find all todos in codebase
(lf-types)          ; Find all type annotations
(docs-for 'symbol)  ; Find docs for specific target
(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

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

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

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

Deprecation

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

Module-Level Documentation

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