메뉴
Reference for The Fold's typed comments and doc forms system. Use when adding type annotations, documentation, todos, or other metadata to Scheme code. Covers (doc ...) syntax, standard tags, search commands, and type checker integration.
| name | doc-forms |
| description | Reference for The Fold's typed comments and doc forms system. Use when adding type annotations, documentation, todos, or other metadata to Scheme code. Covers (doc ...) syntax, standard tags, search commands, and type checker integration. |
| allowed-tools | Bash(./fold:*), Read, Edit, Grep, Glob |
The Fold uses (doc ...) forms for searchable, introspectable annotations that survive in source code.
(define (add x y)
(doc 'type (-> Int Int Int))
(doc 'description "Adds two numbers")
(+ x y))
(doc factorial 'type (-> Int Int))
(define (factorial n)
(if (= n 0) 1 (* n (factorial (- n 1)))))
| Property | Behavior |
|---|---|
| Arguments | NOT evaluated (pure metadata) |
| Return value | void — use in sequences, not value positions |
| Normalization | Stripped — code with/without docs hashes identically |
| Extraction | Tooling reads from source (lf-todo, lf-types) |
| Type authority | Authoritative — (doc f 'type ...) takes precedence over inference |
| Tag | Purpose | Example |
|---|---|---|
'type | Type signature | (doc 'type (-> Int Int)) |
'description | Human-readable description | (doc 'description "Adds two numbers") |
'param | Parameter documentation | (doc 'param 'x "The first operand") |
'returns | Return value description | (doc 'returns "The sum") |
'todo | Work to be done | (doc 'todo "Optimize for large inputs") |
'fixme | Known issue | (doc 'fixme "Edge case with negative numbers") |
'deprecated | Deprecation notice | (doc 'deprecated "Use add-safe instead") |
'since | Version introduced | (doc 'since "1.2.0") |
'see | Related items | (doc 'see 'subtract) |
'note | Implementation note | (doc 'note "Uses memoization internally") |
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
Doc type annotations integrate with both the LSP and type inference:
| Component | Behavior |
|---|---|
| LSP hover | Shows doc-declared types with highest priority |
| Type inference | Uses declared types via lookup-declared-type in core/types/infer.ss |
| Bridge | load-doc-types-into-checker! populates type checker from doc index |
;; The type checker will trust this annotation
(doc my-complex-fn 'type (-> (List Int) (Maybe Int)))
(define (my-complex-fn lst)
;; Complex implementation...
)
| Use Case | When to Use |
|---|---|
(doc 'todo ...) | Colocated with code, for localized improvements (performance, refactoring, cleanup) |
| BBS issue | Tracked work items, features, bugs, cross-cutting concerns, things needing scheduling |
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 ...).
(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...
)
(doc old-api 'deprecated "Use new-api instead. Will be removed in 2.0")
(define (old-api x) (new-api x))
;; At top of file
(doc 'description "Matrix operations for linear algebra")
(doc 'since "1.0.0")
(doc 'see 'linalg/vec)
API quick-reference for key lattice subsystems (FP, Game Theory, SAT, Optics, Statistics, CLP). Use when you need function signatures, module contents, or usage examples for a specific subsystem. Invoke when working with game theory, constraint solving, optics, parsers, or other advanced lattice features.
Search and navigate The Fold's skill lattice using meta-tooling. Use for finding functions, exploring dependencies, type-aware queries, and cross-reference analysis. Invoke when searching for capabilities, exploring the codebase structure, or finding how functions relate.
Troubleshooting guide for The Fold - daemon issues, session corruption, file locations, and common problems. Use when ./fold isn't working, the daemon won't start, or you need to find system files.
Invoke Google's Gemini AI via CLI in headless mode for AI-powered analysis, code generation, and reasoning tasks. Use when you need a second opinion, the user mentions Gemini, needs Google AI capabilities, or requests multi-modal analysis beyond Claude's scope.
Manage issues with The Fold's CAS-native BBS (Bulletin Board System). Use for creating, updating, searching, and tracking issues. Invoke when the user wants to create tickets, find work, check issue status, or manage dependencies.
Developer tools for The Fold - protocols (extensible dispatch), protocol bundles, refactoring toolkit (rename, move, dead code), and template DSL. Use when defining new protocols, refactoring code, or generating S-expressions.