* Documentation of `:documentation`
@ 2022-10-18 1:43 Stefan Monnier
2022-10-18 14:08 ` Eli Zaretskii
2022-10-18 16:05 ` [External] : " Drew Adams
0 siblings, 2 replies; 3+ messages in thread
From: Stefan Monnier @ 2022-10-18 1:43 UTC (permalink / raw)
To: emacs-devel
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] 3+ messages in thread
* Re: Documentation of `:documentation`
2022-10-18 1:43 Documentation of `:documentation` Stefan Monnier
@ 2022-10-18 14:08 ` Eli Zaretskii
2022-10-18 16:05 ` [External] : " Drew Adams
1 sibling, 0 replies; 3+ messages in thread
From: Eli Zaretskii @ 2022-10-18 14:08 UTC (permalink / raw)
To: Stefan Monnier; +Cc: emacs-devel
> 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.
^ permalink raw reply [flat|nested] 3+ messages in thread
* RE: [External] : Documentation of `:documentation`
2022-10-18 1:43 Documentation of `:documentation` Stefan Monnier
2022-10-18 14:08 ` Eli Zaretskii
@ 2022-10-18 16:05 ` Drew Adams
1 sibling, 0 replies; 3+ messages in thread
From: Drew Adams @ 2022-10-18 16:05 UTC (permalink / raw)
To: Stefan Monnier, emacs-devel@gnu.org
> 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.
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2022-10-18 16:05 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-10-18 1:43 Documentation of `:documentation` Stefan Monnier
2022-10-18 14:08 ` Eli Zaretskii
2022-10-18 16:05 ` [External] : " Drew Adams
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.