From 3b0bf359e9ac2d1a0abe1d625ce63fa8c9c6e9b4 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 17 Jun 2023 11:37:19 +0300
Subject: [PATCH] Fix documentation of comment-dwim (bug#64104)

* lisp/newcomment.el (comment-dwim): Doc fix.

* doc/emacs/programs.texi (Comment Commands): More accurate
description of what 'M-;' does when there's no active region.
---
 doc/emacs/programs.texi | 19 +++++++++++--------
 lisp/newcomment.el      |  9 +++++++--
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 69b4f56bee1..a0e0fc06385 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1095,14 +1095,17 @@ were negated.
 
 @findex comment-kill
 @kindex C-u M-;
-  @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
-comment on the current line, along with the whitespace before it.
-Since the comment is saved to the kill ring, you can reinsert it on
-another line by moving to the end of that line, doing @kbd{C-y}, and
-then @kbd{M-;} to realign the comment.  You can achieve the same
-effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
-(@code{comment-dwim} actually calls @code{comment-kill} as a
-subroutine when it is given a prefix argument).
+  @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) when the
+region is not active kills any comment on the current line, along with
+the whitespace before it.  Since the comment is saved to the kill
+ring, you can reinsert it on another line by moving to the end of that
+line, doing @kbd{C-y}, and then @kbd{M-;} to realign the comment.  You
+can achieve the same effect as @kbd{C-u M-;} by typing @kbd{M-x
+comment-kill} (@code{comment-dwim} actually calls @code{comment-kill}
+as a subroutine when it is given a prefix argument).  Invoking
+@code{comment-dwim} with a prefix numeric argument, as in @w{@kbd{C-u
+@var{n} M-;}}, when there's no active region, tells
+@code{comment-kill} to kill comments on @var{n} lines.
 
 @kindex C-c C-c @r{(C mode)}
 @findex comment-region
diff --git a/lisp/newcomment.el b/lisp/newcomment.el
index 022bf3059be..9ae7de70a0e 100644
--- a/lisp/newcomment.el
+++ b/lisp/newcomment.el
@@ -1356,10 +1356,15 @@ is passed on to the respective function."
   "Call the comment command you want (Do What I Mean).
 If the region is active and `transient-mark-mode' is on, call
 `comment-region' (unless it only consists of comments, in which
-case it calls `uncomment-region').
+case it calls `uncomment-region'); in this case, prefix numeric
+argument ARG specifies how many characters to remove from each
+comment delimiter (so don't specify a prefix argument whose value
+is greater than the total length of the comment delimiters).
 Else, if the current line is empty, call `comment-insert-comment-function'
 if it is defined, otherwise insert a comment and indent it.
-Else if a prefix ARG is specified, call `comment-kill'.
+Else, if a prefix ARG is specified, call `comment-kill'; in this
+case, prefix numeric argument ARG specifies on how many lines to kill
+the comments.
 Else, call `comment-indent'.
 You can configure `comment-style' to change the way regions are commented."
   (interactive "*P")
-- 
2.39.2