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

[Stefan Monnier <monnier@iro.umontreal.ca>]

>> There's no such magic.
> Are you saying that `makunbound' should take care of it?

No.  I'm saying that there is no known trick to undo a defcustom.

> Also, it wouldn't hurt to include such tiny diagrams in the doc string
> for `comment-styles' (esp. since it is a defconst).  In this case,
> a set of pictures is worth more than a set of one-liner descriptions.

Again, that would amount to documenting the particular current value of
that variable, rather than the set of possible values and their meaning.
So that would be wrong.  Such documentation can't belong to
comment-styles's docstring; only to the doc of each style defined there.

> BTW, why are all of the various possibilities (align, extra, box etc.)
> defined only for indented comments?

The only reason `plain' exists is because that's what was used in
Emacs≤22.  I strongly discourage people from using it since it often
results in comments that aren't properly indented.

> plain      - Start in column 0 (do not indent)
> indent     - Full comment per line, ends not aligned
> aligned    - Full comment per line, ends aligned
> box        - Full comment per line, ends aligned, + top and bottom
> extra-line - One comment for all lines, end on a line by itself
> multi-line - One comment for all lines, end on last commented line
> box-multi  - One comment for all lines, + top and bottom

Thanks, that seems much better than what I have now.


        Stefan