[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation of `:documentation`
From: |
Eli Zaretskii |
Subject: |
Re: Documentation of `:documentation` |
Date: |
Tue, 18 Oct 2022 17:08:44 +0300 |
> 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.