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