Re: docstrings (WAS: Re: Q: Making an XEmacs package)
On Fri, 14 Dec 2001, Matt Tucker wrote:
[]
I always find this sort of 'feature' weird; it seems like a hack to me.
Would it make sense to change this interface to use a property for user
options instead of an asterisk? Something like:
(defvar pkg-user-var nil
"A user-settable variable"
:user)
Anything (like set-variable) that needed to know whether a variable was
intended to be user-settable would check that property. We could
maintain backward compatibility by setting that property on all
defcustoms by default, and on any defvar that had a docstring starting
with '*'. We could also automatically strip the '*' from docstrings
that included it.
Is this a bad idea? Is it really worth it? :-)
After I wrote the posting I considered that too, but it seems like you got
a very good point here; "features", i.e. properties shouldn't go in
docstrings. I think it's a good idea. Worth it? Don't know.
defcustoms should always set the user property defconst should never set
the user property. Regarding defvar I still feel need of good examples of
when set and not to set it the user property (especially when to _set_
(include "*") it user-intended). I am looking through the big reservoir of
good lisp examples right now, and hope to find a good example there.
In the function space the (interactive ... ) kind of serve that
functionality (sets it to be user-intended)
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.
Jarl