* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
@ 2022-10-18 0:46 Michael Heerdegen
2022-10-18 2:05 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 11+ messages in thread
From: Michael Heerdegen @ 2022-10-18 0:46 UTC (permalink / raw)
To: 58602
Hello,
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'?).
Thanks,
Michael.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-18 0:46 bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures Michael Heerdegen
@ 2022-10-18 2:05 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-10-18 2:20 ` Christopher Dimech
2022-10-18 3:16 ` Michael Heerdegen
0 siblings, 2 replies; 11+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-10-18 2:05 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: 58602
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
^ permalink raw reply related [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-18 2:05 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2022-10-18 2:20 ` Christopher Dimech
2022-10-18 3:16 ` Michael Heerdegen
1 sibling, 0 replies; 11+ messages in thread
From: Christopher Dimech @ 2022-10-18 2:20 UTC (permalink / raw)
To: monnier; +Cc: Michael Heerdegen, 58602
> 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
>
>
>
>
>
>
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-18 2:05 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-10-18 2:20 ` Christopher Dimech
@ 2022-10-18 3:16 ` Michael Heerdegen
2022-10-18 13:34 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 1 reply; 11+ messages in thread
From: Michael Heerdegen @ 2022-10-18 3:16 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 58602
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?
> + 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?
Apart from that, the text is ok for me. Maybe leave out the macro thing
(it's not really suitable to define a macro only for the purpose to
compute the docstring at compile time, and the other methods are
probably as good, so this may be more distracting).
And apart from that, I do not know how to write good documentation as
well.
Thanks,
Michael.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-18 3:16 ` Michael Heerdegen
@ 2022-10-18 13:34 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-10-18 20:13 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 11+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-10-18 13:34 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: 58602
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
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-18 13:34 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2022-10-18 20:13 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-10-18 20:39 ` Drew Adams
2022-10-19 1:24 ` Michael Heerdegen
0 siblings, 2 replies; 11+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-10-18 20:13 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: 58602
I pushed the text below.
Thanks to Eli and Drew for their review.
Stefan
PS: BTW, I noticed that `i :documentation RET` doesn't bring me to this
text, instead it just looks for "documentation" (which matches many
more index entries), disregarding the `:` and making this `@kindex` much
less useful.
PPS: Every time you use this `function-documentation` property, kitten
suffer atrocious pains.
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 8b858e0aa01..94c42ba260d 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -533,6 +533,46 @@ 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 static, but occasionally it can be
+necessary to generate them dynamically. In some cases you can do so
+by writing a macro which generates at compile time the code of the
+function, including the desired documentation string. But you can
+also generate the docstring dynamically by writing
+@code{(:documentation @var{form})} instead of the documentation
+string. This will evaluate @var{form} at run-time when the function
+is defined and use it as the documentation string@footnote{This only
+works in code using @code{lexical-binding}.}. 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 evaluates to a string.
+
+For example:
+@example
+@group
+(defun adder (x)
+ (lambda (y)
+ (:documentation (format "Add %S to the argument Y." x))
+ (+ x y)))
+(defalias 'adder5 (adder 5))
+(documentation 'adder5)
+ @result{} "Add 5 to the argument Y."
+@end group
+
+@group
+(put 'adder5 'function-documentation
+ '(concat (documentation (symbol-function 'adder5) 'raw)
+ " Consulted at " (format-time-string "%H:%M:%S")))
+(documentation 'adder5)
+ @result{} "Add 5 to the argument Y. Consulted at 15:52:13"
+(documentation 'adder5)
+ @result{} "Add 5 to the argument Y. Consulted at 15:52:18"
+@end group
+@end example
+
+
@node Function Names
@section Naming a Function
@cindex function definition
^ permalink raw reply related [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-18 20:13 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2022-10-18 20:39 ` Drew Adams
2022-10-19 1:24 ` Michael Heerdegen
1 sibling, 0 replies; 11+ messages in thread
From: Drew Adams @ 2022-10-18 20:39 UTC (permalink / raw)
To: Stefan Monnier, Michael Heerdegen; +Cc: 58602@debbugs.gnu.org
> I pushed the text below.
Examples LGTM. Thanks for doing this.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-18 20:13 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-10-18 20:39 ` Drew Adams
@ 2022-10-19 1:24 ` Michael Heerdegen
2022-10-19 23:23 ` Michael Heerdegen
1 sibling, 1 reply; 11+ messages in thread
From: Michael Heerdegen @ 2022-10-19 1:24 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 58602
Stefan Monnier <monnier@iro.umontreal.ca> writes:
> I pushed the text below.
Thanks. I really like what you installed.
> PS: BTW, I noticed that `i :documentation RET` doesn't bring me to this
> text, instead it just looks for "documentation" (which matches many
> more index entries), disregarding the `:` and making this `@kindex` much
> less useful.
`Info-index':
#+begin_src emacs-lisp
...
;; Strip leading colon in topic; index format does not allow them.
(if (and (stringp topic)
(> (length topic) 0)
(= (aref topic 0) ?:))
(setq topic (substring topic 1)))
...
#+end_src
Michael.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-19 1:24 ` Michael Heerdegen
@ 2022-10-19 23:23 ` Michael Heerdegen
2022-10-20 9:35 ` Michael Albinus
0 siblings, 1 reply; 11+ messages in thread
From: Michael Heerdegen @ 2022-10-19 23:23 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 58602-done
Michael Heerdegen <michael_heerdegen@web.de> writes:
> > [...] I noticed that `i :documentation RET` doesn't bring me to this
> > text, instead it just looks for "documentation"
> `Info-index':
> ;; Strip leading colon in topic; index format does not allow them.
> (if (and (stringp topic)
> (> (length topic) 0)
> (= (aref topic 0) ?:))
> (setq topic (substring topic 1)))
Yes, deleting that part breaks the i command, so I guess we have to live
with this restriction or find a way to filter out the wanted matches.
Anyway, I think we are done here. Thanks to all, and especially Stefan.
Michael.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-19 23:23 ` Michael Heerdegen
@ 2022-10-20 9:35 ` Michael Albinus
2022-10-20 16:50 ` Drew Adams
0 siblings, 1 reply; 11+ messages in thread
From: Michael Albinus @ 2022-10-20 9:35 UTC (permalink / raw)
To: 58602; +Cc: michael_heerdegen
Michael Heerdegen <michael_heerdegen@web.de> writes:
Hi,
>> > [...] I noticed that `i :documentation RET` doesn't bring me to this
>> > text, instead it just looks for "documentation"
>
>> `Info-index':
>> ;; Strip leading colon in topic; index format does not allow them.
>> (if (and (stringp topic)
>> (> (length topic) 0)
>> (= (aref topic 0) ?:))
>> (setq topic (substring topic 1)))
>
> Yes, deleting that part breaks the i command, so I guess we have to live
> with this restriction or find a way to filter out the wanted matches.
I prefer searching in info via 's', like 's :documentation RET'. This
has also the advantage over the 'i' command to show me dark corners of a
manual which haven't been indexed properly :-)
> Michael.
Best regards, Michael.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures
2022-10-20 9:35 ` Michael Albinus
@ 2022-10-20 16:50 ` Drew Adams
0 siblings, 0 replies; 11+ messages in thread
From: Drew Adams @ 2022-10-20 16:50 UTC (permalink / raw)
To: Michael Albinus, 58602@debbugs.gnu.org; +Cc: michael_heerdegen@web.de
> I prefer searching in info via 's', like 's :documentation RET'. This
> has also the advantage over the 'i' command to show me dark corners of a
> manual which haven't been indexed properly :-)
1. We _can_ have index entries that start with
`:', and we do have some. E.g., these `Key
(Character) Index' entries in the Emacs manual:
* :d (Dired): Operating on Files. (line 124)
* :e (Dired): Operating on Files. (line 136)
* :s (Dired): Operating on Files. (line 132)
* :v (Dired): Operating on Files. (line 128)
And _if you go to that index_ you can follow
those entries to their nodes, with no problem.
And we have command `info-apropos', which
checks all indexes of all manuals. And with
that you can input a string that starts with
`:', and you can get to the locations targeted
by such entries with no problem.
The problem is only (?) with `i' (`Info-index').
With that you can type, say, `:d TAB', which
correctly shows you the completion `:d (Dired)'.
But choosing that completion takes you to the
wrong node - it finds 5 matches for `d (Dired)',
instead of one match for `:d (Dired)'. (It does
find the desired match, but mixed in with other
noise - non-matches.)
2. If we can't fix this directly, then what
Michael A. says maybe points to a workaround
that Emacs could provide.
Many (most?) users won't have a clue about this
difficulty of using `i' with index entries that
start with `:'. And they won't understand
what's going on.
What we could do, is to tell a user, when s?he
tries to use `i' with a name that starts with
`:', that `i' only searches for index entries
with that name _minus_ the `:'. We could then
suggest that s?he use `C-s :<whatever>' instead.
IOW, if this defect of our Info interface isn't
directly fixable then we might at least let
users know that (1) they can't reasonably use
`i :' and (2) they can at least use `C-s :' as
a workaround.
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2022-10-20 16:50 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-10-18 0:46 bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures Michael Heerdegen
2022-10-18 2:05 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-10-18 2:20 ` Christopher Dimech
2022-10-18 3:16 ` Michael Heerdegen
2022-10-18 13:34 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-10-18 20:13 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-10-18 20:39 ` Drew Adams
2022-10-19 1:24 ` Michael Heerdegen
2022-10-19 23:23 ` Michael Heerdegen
2022-10-20 9:35 ` Michael Albinus
2022-10-20 16:50 ` Drew Adams
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).