bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Michael Heerdegen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> +Documentation strings are usually completely static, but occasionally
> +it can be necessary to generate them dynamically.  In some cases this
> +can be done by writing a macro which will generate at compile time the
> +code of the function, including the desired documentation string.
> +But you can also generate the docstring at run-time

I wonder: run-time or eval-time?

> + when the function
> +is defined by writing @code{(:documentation @var{form})} instead of
> +the documentation string@footnote{This only works in code using
> +@code{lexical-binding}.}.  Furthermore, you can also compute the
> +documentation string on the fly when it is requested by setting
> +the @code{function-documentation} property of the function's symbol to
> +a Lisp form that should evaluate to a string.

When is that form evaluated?

Apart from that, the text is ok for me.  Maybe leave out the macro thing
(it's not really suitable to define a macro only for the purpose to
compute the docstring at compile time, and the other methods are
probably as good, so this may be more distracting).

And apart from that, I do not know how to write good documentation as
well.

Thanks,

Michael.