Re: docstrings (WAS: Re: Q: Making an XEmacs package)
On Sun, 16 Dec 2001, Paul Krause wrote:
From: "Jarl Friis" <jarl(a)diku.dk>
> > > BTW: I found another situation where defvar could/should not be
replaced
> > > dy defconst nor defcustom: When some information has to be stored
> > > internally from function call to function call (like the kill-ring and
> > > search-ring). In OO-terms one can think of them as private members.
> >
> > defvar is public. If you want a private variable binding, use let.
>
> Yes, but when you want to store information from one function call to the
> next one, there are only global public space to use, so defvar is it.
Oh, I'm failure as a teacher, that's for sure. Maybe you just needed a
better example. How about if I use one of your examples, the kill-ring?
Edit your simple.el. Delete the defvars for kill-ring and
kill-ring-yank-pointer, and wrap the next three defuns in a let, like this:
(let ((kill-ring nil)
(kill-ring-yank-pointer nil))
(defun kill-new (string &optional replace)
...)
(defun kill-append (string before-p)
...)
(defun current-kill (n &optional do-not-move)
...))
Will not work. since the functions when invoked will refer to kill-ring,
kill-ring-yank-pointer, which in your example is not declared (at time of
invocation).
Test it yourself on:
(let ((private-var "privacy"))
(defun show-private () (message private-var))
(defun change-private (new-private) (setq private-var new-private))
)
Call to show-private will fail unless you call change-private first which
will *create* the public global variable private-var (which has nothing to
do with the one found in line one of the example). The netto-effect of the
example is exactly the same (not sure about byte-compilation) as the
two lines without (let ...):
(defun show-private () (message private-var))
(defun change-private (new-private) (setq private-var new-private))
Untested, and it may not work, because in real life kill-ring is not
private, and other stuff may depend on it being public. But I hope it makes
the concept clear.
Sorry, but to me it's not clear at all what you mean.
Jarl