[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#58602: 29.0.50; Please document (:documentation FORM) spec for closu
From: |
Stefan Monnier |
Subject: |
bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures |
Date: |
Mon, 17 Oct 2022 22:05:06 -0400 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) |
Michael Heerdegen [2022-10-18 02:46:00] wrote:
> I think we need to document this new feature described in etc/NEWS.25:
>
> | ** Lexical closures can use '(:documentation FORM)' to build their
> docstring.
> | It should be placed right where the docstring would be, and FORM is then
> | evaluated (and should return a string) when the closure is built.
>
> at least in the ELisp reference manual (dunno, maybe also in the
> docstring of `lambda' and `defun'?).
[ Our emails crossed: I just sent the following to emacs-devel, but it's
probably better to discuss it here. ]
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.
Tho, maybe there's a way to make it understandable without an example.
I don't know. I need help.
Stefan
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 8b858e0aa01..f85e0498851 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -533,6 +533,20 @@ Function Documentation
compiler emit a warning message when it compiles Lisp programs which
use the deprecated calling convention.
+@cindex Computed documentation string
+@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.
+
@node Function Names
@section Naming a Function
@cindex function definition
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Michael Heerdegen, 2022/10/17
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures,
Stefan Monnier <=
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Christopher Dimech, 2022/10/17
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Michael Heerdegen, 2022/10/17
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Stefan Monnier, 2022/10/18
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Stefan Monnier, 2022/10/18
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Drew Adams, 2022/10/18
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Michael Heerdegen, 2022/10/18
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Michael Heerdegen, 2022/10/19
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Michael Albinus, 2022/10/20
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures, Drew Adams, 2022/10/20