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

[Drew Adams]

> > I came across some variable definition weirdness (unrelated to this
> > bug):
> 
> I must say I have no idea how you got into such a mess.  My only
> explanation would be that some part of the patch did not 
> apply properly.

No, I did not mean to suggest that this had anything to do with your patch.
(And I just "applied" the patch by hand editing.)

> AFAIK, none of those things occur in my usage.

I won't worry about it.  If I have time I'll report it.  I don't have the time
now.

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

Are you saying that `makunbound' should take care of it?

It's pretty easy to see at least some of the problems, I think.  Put these in
different files:

(defcustom foo 1 "The first definition"
 :type 'integer)

(defcustom foo 2 "The second definition"
 :type 'integer)

Then eval the first, then the second, then maybe the first again, using C-M-x.
Use C-h v and see if you don't see at least the wrong file name mentioned at
some points.  I do right away, using the latest Windows binary (built today by
Sean) and emacs -Q.

But all this is outside of bug #7509.  I didn't mean to suggest it had anything
to do with your patch.

> From memory: feel free to test them in a C-mode buffer.

I'll go by your memory.  Someone can correct them later if your memory isn't
perfect.

> plain:
> /*      blabla */
> /*      bla */
> 
> indent
>      /* blabla */
>      /* bla */
>      
> multi-line
>      /* blabla
>       * bla */
> 
> extra-line      
>      /*
>       * blabla
>       * bla
>       */
> 
> aligned
>      /* blabla */
>      /* bla    */
>      
> box
>      /**********/
>      /* blabla */
>      /* bla    */
>      /**********/
> 
> box-multi     
>      /**********
>       * blabla *
>       * bla    *
>       **********/
> 
> When comment-end is the empty string,
> indent=multi-line=extra-line=aligned and box=box-multi.

Thanks.  That helps a lot.  Below are some suggestions.

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.

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

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

And the descriptions make more sense if presented in this order, IMO.

The doc string for `comment-styles' can also point out:

1. That all except for `plain' indent the comment to the current indent level.
2. That when `comment-end' is empty...

Those general rules help understanding and recollection.

HTH.