Re: Documentation strings, declarations, markup, metadata
Lassi Kortela 27 May 2024 20:32 UTC
> - Some systems allow documentation to be written as s-expressions
> (and then string literals are not enough).
Yes. See below.
> - Is documentation generated at compile time or run time?
It should be possible to extract a useful (though perhaps incomplete)
version of the documentation without running any of the code in the
source file.
> - Is documentation available at runtime (in the repl) or just in an
> external tool (say a browser)?
AFAICT that decision has no bearing on syntax.
> For the record, since s-expressions can express anything, I don't think
> a new syntax is needed.
If the aim is to document only procedures, this would work without new
lexical syntax:
(define (foo a b)
(doc markdown "Fools _a_ and _b_.")
...)
In a library:
(define-library (example)
(export foo bar baz)
(import (scheme base))
(doc markdown
"# Example library"
""
"Does things.")
(begin
(define (foo a b)
;; Uses markdown by default since that's what the library used.
(doc "Fools _a_ and _b_.")
...)
(define (bar a b)
;; Uses latex, just to be difficult.
(doc latex "Barters \\em{a} for \\em{b}.")
...)
(define (baz a b)
;; Uses SXML for demonstration.
(doc sxml
"Combines " (em "a") " and " (em "b")
" in a bazillion ways.")
...)))