> On 25 May 2024, at 08:19, Antero Mejr <xxxxxx@antr.me> wrote:
>
> I would like to propose a SRFI for in-source documentation (AKA
> docstrings). The syntax is similar to #| multi-line comments. The
> repository is here:
> https://github.com/pre-srfi/in-source-documentation

The vague plan for R7RS Large is this:

Documentation will be attached as an identifier property (a la SRFI 213).
This means everything can be documented – not only procedures but macros, variables, record types and associated procedures, etc. etc.

There is an implementation to show how simple this idea could be at
<https://codeberg.org/scheme/r7rs/wiki/Identifier-property-use-cases>.
(This is only a sketch.)

This solution also means that a manual page could be generated for a whole library, etc., during compilation of the library itself by attaching special expand-time behaviour to the ‘documentation’ macro. The sketch above doesn’t include this, but it would be easy enough to do with a (current-documentation-exporter) parameter containing a procedure that’s called when documentation is defined, or similar.

If this does happen, it will be specified in the Batteries, because the core mechanism of identifier properties is already there in the Foundations. (This is one Battery that implementations will likely want to adopt into their cores, so that Foundations procedures etc. have interactive documentation available.)

Primarily in order to make it easier to include examples within the documentation which themselves include strings, but also for other longer string literals, I proposed a nestable #" … "# string notation comparable to #| … |#. But I consider the value of this questionable. Emacs Lisp and Common Lisp have both got on perfectly well for the better part of 50 years without this.

As ever, I am not dictator of WG2 and all of these things are still open for debate. My sense is that we have informal consensus for the identifier property based solution, but my #" … "# idea was just a strawman proposal and hasn’t been extensively debated beyond a few minutes’ idle chat on IRC.

Daphne