Documentation strings, declarations, markup, metadata Lassi Kortela (25 May 2024 10:32 UTC)
Re: Documentation strings, declarations, markup, metadata Lassi Kortela (25 May 2024 10:53 UTC)
Re: Documentation strings, declarations, markup, metadata Antero Mejr (25 May 2024 11:07 UTC)
Re: Documentation strings, declarations, markup, metadata Lassi Kortela (27 May 2024 17:02 UTC)
Re: Documentation strings, declarations, markup, metadata Jens Axel Søgaard (27 May 2024 17:22 UTC)
Bodies in COND, CASE, WHEN, UNLESS, and DO Sergei Egorov (04 Jun 2024 20:30 UTC)
Re: Bodies in COND, CASE, WHEN, UNLESS, and DO Jakub T. Jankiewicz (05 Jun 2024 18:50 UTC)
Re: Bodies in COND, CASE, WHEN, UNLESS, and DO Arthur A. Gleckler (19 Jun 2024 17:54 UTC)
Re: Bodies in COND, CASE, WHEN, UNLESS, and DO Jakub T. Jankiewicz (19 Jun 2024 20:10 UTC)
Re: Bodies in COND, CASE, WHEN, UNLESS, and DO Jakub T. Jankiewicz (19 Jun 2024 20:21 UTC)
Re: Documentation strings, declarations, markup, metadata Lassi Kortela (27 May 2024 20:32 UTC)
Re: Documentation strings, declarations, markup, metadata Jakub T. Jankiewicz (27 May 2024 21:41 UTC)
Re: Documentation strings, declarations, markup, metadata Jakub T. Jankiewicz (25 May 2024 11:51 UTC)
Re: Documentation strings, declarations, markup, metadata Jakub T. Jankiewicz (25 May 2024 12:02 UTC)
Re: Documentation strings, declarations, markup, metadata Lassi Kortela (27 May 2024 17:21 UTC)

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