changing the doc string using property `variable-documentation'

["Drew Adams" <drew.adams@oracle.com>]

You can use `defadvice' to add a bit of text to the existing doc string of an
existing function.  But AFAIK there is no way to use `defadvice' to replace or
add to the doc string of a variable.

This seems to be what's called for (for replacing). Correct me if this is not
the best approach:

(put foovar 'variable-documentation "The new doc string")

However, when I put that at the top level of a library that `require''s the
library that defines `foovar', it does not seem to be taken into account. `C-h
v' always shows the original doc string. It doesn't matter whether I load the
source file or the byte-compiled file that has this code.

The following seems to work, but I don't understand why it would make any
difference:
(when t (put foovar 'variable-documentation "The new doc string"))
(Actually, it was tried with (require 'xxx) instead of t.)

Grepping the Emacs source files, I found a better solution, in `cc-vars.el'.
It's apparently enough to add a vacuous `defvar':

(defvar foovar)
(put foovar 'variable-documentation "The new doc string")

I don't understand why that would be, or how this works (or why it doesn't work
without the `defvar', especially since the library with the real `defvar' was
already loaded/required).

So that's what I'm using now. Is this in fact the best way to accomplish this?
If not, what is?

I'd also be grateful for an explanation of what's going on (e.g. why the `put'
doesn't work at top level without the vacuous `defvar'). Thx.

--

P.S. I think this comment in cc-vars.el is wrong. It seems to work for me also
in prior versions (e.g. Emacs 20).

;; C-h v will read this documentation only for versions of GNU
;; Emacs from 22.1.