Retropikzel <xxxxxx@iki.fi> writes:

> Do I understand correctly that this is meant for kind of "one line"
> documentation not for something long form?

No, it can do one line or multiple.

> Not like this:
>
> ```
> #?
>
> ## plus
>
> Arguments:
>
> - x (number)
> - y (number)
>
> Returns:
>
> - (number) X and y added together
>
> ?#
> (define plus
> (lambda (x y)
>    (+ x y)))
> ```

That will document the plus procedure.

> But like this:
>
> ```
> #? Adds x and y together ?#
> (define plus
>    (lambda (x y)
> ```

That will also work.

> Or should it be, since you mentioned docstrings, like this?:
>
> ```
> (define plus
>    #? Adds x and y together ?#
>    (lambda (x y)
> ```

That will document the lambda procedure, but not the binding of that
procedure to the `plus` identifier.

> What happens if (read: when) I try to do this?:
>
> ```
> (define plus
>    #? Adds x and y together ?#
>    (lambda (#?number?# x #?number?# y)
>      (+ x y)))
> ```

This documents the entire lambda with " Adds x and y together ", the x
argument of the lambda with the text "number", and the y argument with
the text "number".

Keep in mind that the exporter needs to be able to understand the forms
it reads using `read-doc`.

A basic exporter may only recognize the first version, and ignore the
rest. A smarter exporter may be able create well-formatted documentation
for many different forms.

The `read-doc` procedure is general enough to support a wide range of
exporters, and LSP servers as well. But defining or providing the
exporter is beyond the scope of this SRFI. By "exporter", I am referring
to a program like Doxygen or Sphinx.