Documentation of `:documentation`

Documentation of `:documentation`

[Stefan Monnier]

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

Re: Documentation of `:documentation`

[Eli Zaretskii]

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

RE: [External] : Documentation of `:documentation`

[Drew Adams]

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

Minor text suggestions:

1. completely static -> static

2. Less passive voice: "You can..." instead of "this
   can be done" etc.

3. Present or imperative, not future: "generates", not
   "will generate".

4. "is defined by" -> "is defined, by"

5. Say what FORM is.  I don't see described here what
   "(:documentation FORM)" is/means.  E.g., say that
   FORM is evaluated (when?) and its value is used
   (when?) as the doc string.  (No need to say that
   the value "should" be a string.)

6. "on the fly when it is requested" means what?
   If "on the fly" is understood here (not sure it
   is) then how is "on the fly" different from "on
   the fly when it is requested"?

7. "Furthermore, you can also" -> "You can also".

8. "when it is requested by" -?-> "when it is
   requested, by".

9. "should evaluate to" -> "evaluates to".

10. So far in the Elisp manual, we don't use "computed"
    followed by a noun (well, there's one occurrence
    of "computed value").  We use "programmed", but
    only for "programmed completion".  Dunno what term
    is best here, where you use "Computed doc string".
    But that's used only in an index entry, which is
    fine (but "Computed" -> "computed").

Less minor user-message comments:

11. How does using (:documentation FORM) differ in
    behavior, and what you can do with it (use cases),
    from "setting the `function-documentation' property
    of the function's symbol to a Lisp form" whose
    value is used as the doc string?

12. Yes, an example would help.

HTH.