[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: |
Christopher Dimech |
Subject: |
bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures |
Date: |
Tue, 18 Oct 2022 04:20:43 +0200 |
> Sent: Tuesday, October 18, 2022 at 2:05 PM
> From: "Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of
> text editors" <bug-gnu-emacs@gnu.org>
> To: "Michael Heerdegen" <michael_heerdegen@web.de>
> Cc: 58602@debbugs.gnu.org
> Subject: bug#58602: 29.0.50; Please document (:documentation FORM) spec for
> closures
>
> 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.
:documentation would then be safe for the majority of code once emacs completes
the lexical binding transition. Would this be correct?
> > 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, 2022/10/17
- bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures,
Christopher Dimech <=
- 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