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

[Drew Adams]

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

No, we would be documenting the _default_ value.  Nothing wrong with that.  It
serves as a model, a particular value, yes, but also a good example.  And the
value that defines the behavior (the possibilities) out of the box - good to
know.

Both understanding the default behavior/value and having it as a model are
useful.

> So that would be wrong.  Such documentation can't belong to
> comment-styles's docstring; only to the doc of each style 
> defined there.

Either nothing is defined there (it's just one possible value, as you point out)
or everything is defined there (it's the default value, defining all the
behavior possibilities you get if you don't change anything).  You cannot have
it both ways. ;-)

I'd say that we should describe the default value in the doc string (and not
just inside the value itself), because I think that will help users.  The doc
string just needs to make clear that this description applies to the _default
value_, which serves as _an example_.

No matter how good the one-liner descriptions we might come up with, they are no
match for the little samples you sent me.  Once you see them it's all clear, but
until then a reader is really only guessing.  IMO.

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

I strongly prefer `plain'. ;-)  But I don't program in C.  And I don't pretend
to speak for anyone but myself.

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

You're welcome.  Thanks for making the changes.