[Top][All Lists]
[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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Convention about `*' in docstrings?,
Bastien <=