build/dev/lib/_pkg/sigil-stdlib/style/documentation.md

2# Documentation

4> Docstring format and conventions.

6## Comment Types

8Sigil uses semicolon count to distinguish comment purposes:

10| Prefix | Purpose |

11|--------|---------|

12| `;;` | Internal comments, section headers |

13| `;;;` | Docstrings for exported definitions |

15## Docstring Format

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

19```scheme

20;;; Calculate the factorial of a non-negative integer.

21;;;

22;;; Returns n! (n factorial). Raises an error for negative inputs.

23;;;

24;;; ```

25;;; (factorial 5) ; => 120

26;;; (factorial 0) ; => 1

27;;; ```

28(define (factorial n)

29 (if (zero? n)

30 1

31 (* n (factorial (- n 1)))))

32```

34### Structure

361. **Summary line** - First line, one sentence describing what it does

372. **Details** - Additional explanation (optional)

383. **Examples** - Code block showing usage

40### Summary Line

42- Start with a verb: "Calculate", "Return", "Check", "Convert"

43- Complete sentence, ends with period

44- Fits on one line

46```scheme

47;;; Return the first element of a list.

48(define (first lst) ...)

50;;; Check if a string contains only whitespace.

51(define (blank? str) ...)

53;;; Convert a timestamp to ISO 8601 format.

54(define (timestamp->iso ts) ...)

55```

57## Module Docstrings

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

61```scheme

62;;; (sigil http client) - HTTP client for making web requests.

63;;;

64;;; Provides procedures for GET, POST, and other HTTP methods.

65;;; Supports both synchronous and asynchronous operation.

66;;;

67;;; ```

68;;; (import (sigil http client))

69;;;

70;;; (define response (http-get "https://api.example.com/data"))

71;;; (response-body response)

72;;; ```

74(define-library (sigil http client)

75 ...)

76```

78## Section Headers

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

82```scheme

83;; ============================================================

84;; String Utilities

85;; ============================================================

87;;; Split a string by separator.

88(define (string-split str sep) ...)

90;;; Join strings with separator.

91(define (string-join strs sep) ...)

93;; ============================================================

94;; Internal Helpers

95;; ============================================================

97;; Not exported, no docstring needed

98(define (internal-helper x) ...)

99```

100

101## Code Examples

102

103Use fenced code blocks (no language specifier needed):

104

105```scheme

106;;; Filter elements matching a predicate.

107;;;

108;;; Returns a new list containing only elements where

109;;; (pred element) returns true.

110;;;

111;;; ```

112;;; (filter even? '(1 2 3 4 5)) ; => (2 4)

113;;; (filter string? '(1 "a" 2 "b")) ; => ("a" "b")

114;;; ```

115(define (filter pred lst) ...)

116```

117

118Show both input and expected output:

119

120```scheme

121;;; ```

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

123;;; ```

124```

125

126## Syntax Documentation

127

128Document macros with their expansion pattern:

129

130```scheme

131;;; Bind a single variable.

132;;;

133;;; Shorthand for let with one binding.

134;;;

135;;; ```

136;;; (let1 x 10

137;;; (+ x 1))

138;;; ; Expands to:

139;;; ; (let ((x 10)) (+ x 1))

140;;; ```

141(define-syntax let1 ...)

142```

143

144## What to Document

145

146**Always document:**

147- Exported procedures

148- Exported macros/syntax

149- Module purpose

150

151**Optional:**

152- Private helpers (if complex)

153- Internal constants

154

155**Never:**

156- Obvious one-liners unless the name is unclear

157- Implementation details that may change

158

159## Tone

160

161- Be concise and direct

162- Use present tense: "Returns" not "Will return"

163- Use active voice: "Raises an error" not "An error is raised"

164- Address the reader implicitly: "Use X for Y" not "You should use X for Y"