Notre avis

Cette compétence fournit une référence pour utiliser les formulaires de commentaires typés et de documentation (doc ...) de The Fold afin d'ajouter des métadonnées comme les annotations de type, descriptions, tâches et avis de dépréciation dans du code Scheme, avec intégration au vérificateur de types et aux commandes de recherche.

Points forts

Annotations de type faisant autorité qui priment sur l'inférence.
Métadonnées colocalisées qui survivent dans le code source.
Recherchables via des commandes comme lf-todo et lf-types.
Intégration avec le LSP et le vérificateur de types.

Limites

Applicable uniquement au dialecte The Fold de Scheme.
Nécessite la connaissance de la syntaxe spécifique des balises.
Les métadonnées sont supprimées lors de la normalisation, donc non disponibles à l'exécution.

Quand l'utiliser

Utilisez cette compétence lorsque vous devez ajouter des annotations de type, de la documentation ou des éléments de travail directement dans du code Scheme écrit dans The Fold, afin d'améliorer les outils et la clarté du code.

Quand l'éviter

N'utilisez pas cette compétence en dehors d'un codebase The Fold ou lorsque vous avez besoin de métadonnées accessibles à l'exécution, car les formulaires doc sont purement des annotations à la compilation.

Exemples

Add type annotation to a function

Add a '(doc 'type (-> Int Int Int))' annotation to the 'add' function in the current Scheme file.

Find all todos in codebase

Run lf-todo to list all todo annotations in the project.

Document a function with multiple tags

Add type, description, param, returns, and todo documentation to the 'binary-search' function using doc forms.

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

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

| 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 |

Standard Tags

| 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") |

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:

| 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 |

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

| 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 ...).

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)

Système de formulaires de documentation typés

Recommandé pour