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

["Drew Adams" <drew.adams@oracle.com>]

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

Yes, I recognize that.  It's a general problem.  But some individual cases can
be improved to some extent.  But modularity is impacted, since we have two
variables.  It could be OK for one to refer to the other, but in this case one
is a defcustom (so the values should be user-recognizable) and the other is a
defconst (so the values need to be the Lisp symbols).

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

If that can be done so that updates work automatically, that would be good.
IOW, I think you're saying that we would update the descriptions in only one
place, and they would appear in both places.

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

The possible values seem to include `box' and `box-multi' (at least I see those
in the default alist value).  Neither of those is described in the doc string.

Comment region styles of the form (STYLE . (MULTI ALIGN EXTRA INDENT)).
STYLE should be a mnemonic symbol.
MULTI specifies that comments are allowed to span multiple lines.
ALIGN specifies that the `comment-end' markers should be aligned.
EXTRA specifies that an extra line should be used before and after the
  region to comment (to put the `comment-end' and `comment-start').
INDENT specifies that the `comment-start' markers should not be put at the
  left margin but at the current indentation of the region to comment.
If INDENT is `multi-char', that means indent multi-character
  comment starters, but not one-character comment starters.

Value: 
((plain nil nil nil nil)
 (indent nil nil nil t)
 (indent-or-triple nil nil nil multi-char)
 (aligned nil t nil t)
 (multi-line t nil nil t)
 (extra-line t nil t t)
 (box nil t t t) ; <=====================
 (box-multi t t t t)) ; <================