emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Convention about `*' in docstrings?


From: Bastien
Subject: Convention about `*' in docstrings?
Date: Mon, 25 Feb 2008 09:06:55 +0000
User-agent: Gnus/5.110007 (No Gnus v0.7) Emacs/23.0.60 (gnu/linux)

I need to be enlightened about the use of `*' in docstrings.  

Last changes by Miles (in mail-source.el and nnmail.el) and Glenn (in
smtpmail.el) removed the leading `*' in some docstrings.

I somewhat thought that using `*' in docstrings was obsolete, and these
changes seem to confirm that (to a limited extent: no case can "confirm"
a rule.)

But I read the manual and found this:

,----[ (info "(elisp)Documentation Tips") ]
| * When you define a variable that users ought to set interactively,
|   you normally should use `defcustom'.  However, if for some reason
|   you use `defvar' instead, start the doc string with a `*'.  *Note
|   Defining Variables::.
`----

Fair enough. 

,----[ (info "(elisp)Defining Variables") ]
|   If the variable is a user option that users would want to set
|   interactively, you should use `*' as the first character of
|   DOC-STRING.  This lets users set the variable conveniently using the
|   `set-variable' command.  Note that you should nearly always use
|   `defcustom' instead of `defvar' to define these variables, so that
|   users can use `M-x customize' and related commands to set them.
`----

Is this still accurate?  

Can someone provide a simple summary of good practices regarding `*' in
docstrings?  Thanks in advance.

-- 
Bastien




reply via email to

[Prev in Thread] Current Thread [Next in Thread]