GNU bug report logs - #7509
24.0.50; doc for `comment-style' and `comment-styles'

Previous Next

Full log

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; doc for `comment-style' and `comment-styles'
Date: Sun, 28 Nov 2010 11:42:46 -0800

1. User option `comment-style' should be documented in the Emacs manual.
It is in neither that manual nor the Elisp manual.

Don't bother to answer that not all options are described in the manual
- your stock reply.  This is a bug report about a _particular_ option's
(lack of) doc.

2. The doc string of `comment-style' should explain what each of the
possible values is/does.  It should not refer you to the doc string for
`comment-styles' (a defconst).

The `comment-style' doc string should explain the values in a way that
makes sense for `M-x customize-option custom-style', that is, not just
with reference to the Lisp values but in terms of the `Value Menu'
labels.

Users of Customize should not just be sent to a defconst doc string that
requires them to somehow map the `Value Menu' labels against the Lisp
values.  It is perfectly OK to _also_ say "see also `comment-style'.
And the latter's doc string _should_ of course describe the Lisp values.

3. The doc string of `comment-styles' is anyway out of date.  Not all of
the values are described.  This means that users trying to customize
`comment-style' are lost.

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-11-22 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.