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