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

[Drew Adams]

> Can you try the patch below and tell us if it addresses your problem
> (I'm not that happy with the doc for some of those styles, so if you
> have suggestions for improvements, I'm all ears).

Thanks for working on this.

I came across some variable definition weirdness (unrelated to this bug):

I edited the code in another file (a copy), to apply the patch, then used C-M-x
to redefine each var.

In Customize for `comment-style' I clicked the link for `comment-styles', and it
said the var is defined in `newcomment.el' (I evaled the new definition in a
different file).  And the doc was still the doc of the old definition.

Also, the Customize buffer for `comment-style' said that the value was changed
outside Customize (dunno if defining a defcustom should be considered that way,
but whatever...).

I clicked Restore to Standard Setting, and I got this error: (void-variable
indent).  From then on whenever I clicked the State button, instead of getting a
State menu I got this:

Debugger entered--Lisp error: (void-variable indent)
  eval(indent)
  (equal (eval (car cval)) (default-value symbol))
  (not (equal (eval (car cval)) (default-value symbol)))
  (and cval (default-boundp symbol) (not (equal (eval (car cval)) (default-value
symbol))))
  (let* ((symbol (widget-get-tag-or-value widget))...)
  (lambda (widget) (let* ((symbol (widget-get-tag-or-value widget))...)
  custom-menu-filter((("Set for Current Session" custom-variable-set ...)
  custom-variable-action((custom-variable :documentation-shown t...)
  widget-apply((custom-variable :documentation-shown t...)
  widget-parent-action((custom-magic :args (nil) :parent (custom-variable...)
  widget-apply((custom-magic :args (nil) :parent (custom-variable...)
  widget-parent-action((choice-item :help-echo "Change the state of this
item."...)
  widget-apply((choice-item :help-echo "Change the state of this item."...)
  widget-apply-action((choice-item :help-echo "Change the state of this
item."...)
  byte-code("...

I started over (emacs -Q)...  Same thing, but this time I didn't restore to
standard setting (so no error was raised).

Seems there is something buggy about the Customize code or C-M-x or both.  C-M-x
on a defcustom or a defconst in file foo.el should not give a *Help* buffer that
says that the var is defined in file bar.el, and it should not give the doc from
a definition in bar.el.

I tried (makunbound 'comment-style) and (makunbound 'comment-styles), then used
`C-M-x' again.  The `makunbound' calls worked OK (as shown by `boundp').  And
C-h v then showed the correct doc strings.  But it also still showed the wrong
file name: "comment-styles is a variable defined in `newcomment.el'".  So *Help*
shows a doc string that is not even present in the file it mentions!

What's the magic to competely undo a defcustom or defconst - `makunbound'
doesn't seem to be enough.


Anyway, back to this bug...

The problem with my commenting on the description text is that I don't know what
the various behaviors are, so I can't suggest doc improvements.  Yes, that means
that the current descriptions are inadequate, at least for me - I still have no
clue what is meant.

Can you please give me an example of each style, for a context/language
appropriate to that style?  Then I can try to suggest better one-liner
descriptions.  If the behavior is different depending on whether comment-end is
nil, then give me an example of each behavior.

Also, if a given style has no effect (or has the same effect as some other
style) when comment-end is nil then the doc should say that.  E.g., if
`box-multi' is the same as `multi-line' (just a wild guess) for a language where
there is no comment-end, then we should point this out somehow.

The only style description I really understand is this one: "Comment in column
0".  My (minor) suggestion here is to say "comment chars" or "comment
beginning", not just "comment".

In sum, for me to help here, you will need to give me more info about the
styles.  Don't try to word the descriptions; just give me a more verbose
explanation/description - or examples.  Then I'll suggest some descriptive text.

Other than the particular text to be used, the patch (design) seems good to me.

Another minor nit: "See `comment-styles' for a list..." should say "See
`comment-styles' for the list...".  It is precisely the same list as what is
available here.

HTH.