[External] : Supplying DOC string in a `defun' using `defvar'

[ludvig-faddeev]

A useful tool would be to allow one to append to a docstring using a variable.

User could write a brief description, and append more details from a defvar.

I like my functions to be succinct without an overly long docstring.  This makes
the implementation code readily displayed on the visible window.

> Sent: Tuesday, June 01, 2021 at 11:31 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> Drew Adams <drew.adams@oracle.com> writes:
>
> > (let ((toto "WHAT?!!!!"))
> >   (put 'bar 'function-documentation toto))
> >
> > (describe-function 'bar)
>
> Yes, the `function-documentation` property.  Its value can even be an
> expression, and that will be evaluated whenever the documentation is
> requested.  In one of the simplest cases, that expression is a variable
> holding the documentation:
>
> #+begin_src emacs-lisp
> (defvar my-doc "A test function
>
> And this is its documentation")
>
> (defun test () 1)
>
> (put 'test 'function-documentation 'my-doc)
>
> ;; Try C-h f test RET
> #+end_src
>
> When you change the value of `my-doc' the documentation of `test'
> changes magically.
>
> There are cases in Emacs where the expression is used to generate a
> docstring dynamically - `pcase' is one example.
>
>
> Michael.
>
>
>