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

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

Michael Heerdegen [2022-10-18 05:16:49] wrote:
> 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?

In my world these are two words to say the same thing.

>> + 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?

When the documentation string "is requested".


        Stefan