changing the doc string using property `variable-documentation'

changing the doc string using property `variable-documentation'

[Drew Adams]

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.

changing the doc string using property `variable-documentation'

[Stephen J. Turnbull]

Drew Adams writes:

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

Should that be 'foovar?  `put' is a function.

RE: changing the doc string using property `variable-documentation'

[Drew Adams]

>  > (put foovar 'variable-documentation "The new doc string")
> 
> Should that be 'foovar?  `put' is a function.

Yes, sorry; that's what I meant. Thx.

RE: changing the doc string using property `variable-documentation'

[Drew Adams]

Resending (with missing ' typo corrected).


Is there a byte compiler bug here?

What's the (logical) relation between the vacuous `defvar' and updating the doc
string? (Why?)

If there is byte-compiler no bug here, shouldn't this use of `defvar' be
documented, as the (weird) cliche for updating a doc string at top level?

Should there be something along the lines of `defadvice' for variables, to let
you update a variable's doc string?

What about the apparently erroneous cc-vars.el comment?



-----Original Message-----
From: Drew Adams Sent: Tuesday, September 01, 2009 9:53 AM

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.