Documentation

Docstring format and conventions.

Comment Types

Sigil uses semicolon count to distinguish comment purposes:

Docstring Format

Docstrings use ;;; and appear immediately before the definition.

;;; Calculate the factorial of a non-negative integer.
;;;
;;; Returns n! (n factorial). Raises an error for negative inputs.
;;;
;;; ```
;;; (factorial 5)   ; => 120
;;; (factorial 0)   ; => 1
;;; ```
(define (factorial n)
  (if (zero? n)
      1
      (* n (factorial (- n 1)))))

Structure

1. Summary line - First line, one sentence describing what it does
2. Details - Additional explanation (optional)
3. Examples - Code block showing usage

Summary Line

• Start with a verb: "Calculate", "Return", "Check", "Convert"
• Complete sentence, ends with period
• Fits on one line

;;; Return the first element of a list.
(define (first lst) ...)

;;; Check if a string contains only whitespace.
(define (blank? str) ...)

;;; Convert a timestamp to ISO 8601 format.
(define (timestamp->iso ts) ...)

Module Docstrings

Document the module before define-library. Start with the module name:

;;; (sigil http client) - HTTP client for making web requests.
;;;
;;; Provides procedures for GET, POST, and other HTTP methods.
;;; Supports both synchronous and asynchronous operation.
;;;
;;; ```
;;; (import (sigil http client))
;;;
;;; (define response (http-get "https://api.example.com/data"))
;;; (response-body response)
;;; ```

(define-library (sigil http client)
  ...)

Section Headers

Use ;; (not ;;;) for internal section headers:

;; ============================================================
;; String Utilities
;; ============================================================

;;; Split a string by separator.
(define (string-split str sep) ...)

;;; Join strings with separator.
(define (string-join strs sep) ...)

;; ============================================================
;; Internal Helpers
;; ============================================================

;; Not exported, no docstring needed
(define (internal-helper x) ...)

Code Examples

Use fenced code blocks (no language specifier needed):

;;; Filter elements matching a predicate.
;;;
;;; Returns a new list containing only elements where
;;; (pred element) returns true.
;;;
;;; ```
;;; (filter even? '(1 2 3 4 5))     ; => (2 4)
;;; (filter string? '(1 "a" 2 "b")) ; => ("a" "b")
;;; ```
(define (filter pred lst) ...)

Show both input and expected output:

;;; ```
;;; (string-split "a,b,c" ",")  ; => ("a" "b" "c")
;;; ```

Syntax Documentation

Document macros with their expansion pattern:

;;; Bind a single variable.
;;;
;;; Shorthand for let with one binding.
;;;
;;; ```
;;; (let1 x 10
;;;   (+ x 1))
;;; ; Expands to:
;;; ; (let ((x 10)) (+ x 1))
;;; ```
(define-syntax let1 ...)

What to Document

Always document:

• Exported procedures
• Exported macros/syntax
• Module purpose

Optional:

• Private helpers (if complex)
• Internal constants

Never:

• Obvious one-liners unless the name is unclear
• Implementation details that may change

Tone

• Be concise and direct
• Use present tense: "Returns" not "Will return"
• Use active voice: "Raises an error" not "An error is raised"
• Address the reader implicitly: "Use X for Y" not "You should use X for Y"