bug#7509: 24.0.50; doc for `comment-style' and `comment-styles'

[Stefan Monnier <monnier@IRO.UMontreal.CA>]

> 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