From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-devel@gnu.org>
Subject: changing the doc string using property `variable-documentation'
Date: Tue, 1 Sep 2009 09:53:16 -0700 [thread overview]
Message-ID: <61F7D8EAE62B4D3F9FA423635C3D9821@us.oracle.com> (raw)
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.
next reply other threads:[~2009-09-01 16:53 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2009-09-01 16:53 Drew Adams [this message]
2009-09-02 2:58 ` changing the doc string using property `variable-documentation' Stephen J. Turnbull
2009-09-02 3:24 ` Drew Adams
-- strict thread matches above, loose matches on Subject: below --
2009-09-05 21:32 Drew Adams
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=61F7D8EAE62B4D3F9FA423635C3D9821@us.oracle.com \
--to=drew.adams@oracle.com \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.