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.