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

Previous Next

Full log

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

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7509 <at> debbugs.gnu.org
Subject: Re: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles'
Date: Sun, 28 Nov 2010 16:01:11 -0500

> 1. User option `comment-style' should be documented in the Emacs manual.

Indeed.  It probably doesn't need to be in the Elisp manual, but the
User manual should mention it.

> 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).

From a modularity point of view, this is somewhat problematic.
So I have philosophical problems with this, although I agree that the
current docstring doesn't work well in Custom.

Maybe a solution is to extend comment-styles so it includes a short
docstring for each entry that can then be used for the label on each
value in the "Value menu" of comment-style.

> 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.

I don't understand: the docstring of comment-styles (like all other
variable docstrings) doesn't describe its current value, but rather what
are its possible value(s) and what they mean.  It seems to be just as
up-to-date as when I originally wrote it (that part of the code hasn't
changed since, AFAIK).


        Stefan

Previous Next

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