bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Michael Heerdegen]

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.

bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

[Christopher Dimech]

> 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]

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.

bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Drew Adams]

> I pushed the text below.

Examples LGTM.  Thanks for doing this.

bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Michael Heerdegen]

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.

bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Michael Heerdegen]

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.

bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Michael Albinus]

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.

bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures

[Drew Adams]

> 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.