Re: Documentation of `:documentation`

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Mon, 17 Oct 2022 21:43:50 -0400
> 
> Someone pointed out that I forgot to document the `:documentation`
> thingy for functions.
> 
> I came up with the text below, but I find it too terse.  I'm wondering
> whether maybe it should be expanded to a subsubsection maybe, where
> I could more easily put some examples.

Thanks.

> +@cindex Computed documentation string

Index entries should avoid using capital letters as much as possible
(to avoid differences due to locale-dependent sorting).

> +@kindex{:documentation}
> +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 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.

This is quite clear, but I think an example or two will make it even
mode clear.