Re: comment-multi-line docstring

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

> From C-h v comment-multi-line:

>     *Non-nil means M-x comment-indent-new-line continues comments, with no
>      new terminator or starter.
>     This is obsolete because you might as well use C-j.

> Is that "This is obsolete" really accurate?

I think it isn't.

IIRC, when I wrote newcomment.el I was pretty concerned about backward
compatibility (I wanted to make sure that the package was going to be
accepted as a *replacement* for the old commenting code, rather than
like cperl-mode and ibuffer), so I preserved everything as much as I could.
This variable was one I didn't understand at the time, so I just did my best
to preserve the behavior (without actually knowing it, so it was basically
preserving the code) and touched it as little as possible.

I've since learned a bit more about this variable (mostly thanks to
bug reports from Martin Stjernholm) which seems to be actually used
by default in CC-mode and which I've since also used in sgml-mode.

So I think the docstring should be rewritten to remove the `obsolete' part
and to better explain what it does.  AFAIk, what it does it change
auto-fill-mode so that it doesn't add a "end+start" pair of comment markers
when breaking a line.


        Stefan