comment-multi-line docstring

comment-multi-line docstring

[Luc Teirlinck]

>From C-h f 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.

    You can customize this variable.

Is that "This is obsolete" really accurate?  The direct effect on an
interactively used `M-x comment-indent-new-line' might be obsolete,
but is this not used by auto-fill-mode?  If so, should the docstring
not mention this?

Assuming this _really_ is obsolete, then why clutter a Custom buffer
with it?

Sincerely,

Luc.

Re: comment-multi-line docstring

[Luc Teirlinck]

>From my previous message:

   From C-h f comment-multi-line:

C-h v comment-multi-line, of course.

Sincerely,

Luc.

Re: comment-multi-line docstring

[Stefan]

> 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

Re: comment-multi-line docstring

[Luc Teirlinck]

Stefan Monnier wrote:

   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.

What about the following new docstring?  Too bad that \\[...] does not
recognize aliases.  I had to use \\[indent-new-comment-line] to get
C-M-j.  \\[comment-indent-new-line] produced `M-x comment-indent-new-line'.


===File ~/newcomment-diff===================================
*** newcomment.el	07 Sep 2004 09:18:13 -0500	1.79
--- newcomment.el	26 Sep 2004 17:26:27 -0500	
***************
*** 215,222 ****
  
  ;;;###autoload
  (defcustom comment-multi-line nil
!   "*Non-nil means \\[comment-indent-new-line] continues comments, with no new terminator or starter.
! This is obsolete because you might as well use \\[newline-and-indent]."
    :type 'boolean)
  
  (defcustom comment-empty-lines nil
--- 215,227 ----
  
  ;;;###autoload
  (defcustom comment-multi-line nil
!   "*Non-nil means `comment-indent-new-line' continues comments.
! That is, it inserts no new terminator or starter.
! This affects `auto-fill-mode', which is the main reason to
! customize this variable.
! 
! It also affects \\[indent-new-comment-line].  However, if you want this
! behavior for explicit filling, you might as well use \\[newline-and-indent]."
    :type 'boolean)
  
  (defcustom comment-empty-lines nil
============================================================