Re: docstrings (WAS: Re: Q: Making an XEmacs package)
-- Jarl Friis <jarl(a)diku.dk> spake thusly:
On 14 Dec 2001, Stephen J. Turnbull wrote:
> Jarl> In the lispref there's a section describing Defining Global
> Jarl> Variables. A lot of stuff regarding defvar is mentioned and
> Jarl> one should start the documentation string with an asteriks
> Jarl> to indicate it's a user option, the
>
> This is used by (hyper-)?apropos. You should still do it in
> defcustoms.
It affects (hyper-)?apropos with an indication that it is a
user-variable, no other way right?
Related is the affect to `set-variable' which completion includes it
if and only if the doc string contains an asterisk.
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? :-)
Attachments:
- attachment.sig (application/pgp-signature — 232 bytes)