From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 26 Sep 2024 11:24:18 +0000 (+0300)
Subject: ; Fix documentation of last change
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=108a651336b718859f9c1beea8822bf77bcb19da;p=emacs.git

; Fix documentation of last change

* lisp/vc/diff-mode.el (diff-ask-before-revert-and-kill-hunk): Add
':version' tag.
(diff-revert-and-kill-hunk, diff-apply-buffer): Doc fixes.

* etc/NEWS:
* doc/emacs/files.texi (Diff Mode): Fix last change; add indexing.

(cherry picked from commit c86e7a29e78e75b487ea36f0711f327f66f93c10)
---

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index c9d4d0b6b24..59baa304eda 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1673,6 +1673,7 @@ In a multi-file patch, kill the current file part.
 
 @findex diff-apply-hunk
 @cindex patches, applying
+@cindex reverse-apply diffs
 @item C-c C-a
 Apply this hunk to its target file (@code{diff-apply-hunk}).  With a
 prefix argument of @kbd{C-u}, revert this hunk, i.e.@: apply the
@@ -1682,18 +1683,18 @@ hunk to the ``old'' version of the file instead.
 
 @findex diff-revert-and-kill-hunk
 @item C-c M-r
-Reverse-apply this hunk to the target file, and then kill it
+Revert this hunk, and then remove the hunk from the diffs
 (@code{diff-revert-and-kill-hunk}).  Save the buffer visiting the target
 file.
 
 This command is useful in buffers generated by @w{@kbd{C-x v =}} and
 @w{@kbd{C-x v D}} (@pxref{Old Revisions}).  These buffers present you
-with a view of the changes you've made, and then you can use this
-command to drop changes you didn't intend, or no longer want.
+with a view of the changes you've made, and you can use this command to
+undo changes you didn't intend to do, or no longer want.
 
 This is a destructive operation, so by default, this command asks you to
-confirm you really want to reverse-apply and kill the hunk.  You can
-customize @code{diff-ask-before-revert-and-kill-hunk} to change that.
+confirm you really want to revert and kill the hunk.  You can customize
+@code{diff-ask-before-revert-and-kill-hunk} to control that.
 
 @findex diff-apply-buffer
 @item C-c @key{RET} a
diff --git a/etc/NEWS b/etc/NEWS
index ba63c6ce9ea..19bc9c3c43f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -330,8 +330,9 @@ command attempts to look up and copy the text in-between the hunks.
 
 +++
 *** New command 'diff-revert-and-kill-hunk' bound to C-c M-r.
-This command reverse-applies the hunk at point, and then kills it.
-This is useful in buffers generated by C-x v = and C-x v D.
+This command reverts the hunk at point (i.e., applies the reverse of the
+hunk), and then removes the hunk from the diffs.  This is useful to undo
+commits when you are in buffers generated by 'C-x v =' and 'C-x v D'.
 
 ** php-ts-mode
 
diff --git a/lisp/vc/diff-mode.el b/lisp/vc/diff-mode.el
index ca06d189343..318389be2dc 100644
--- a/lisp/vc/diff-mode.el
+++ b/lisp/vc/diff-mode.el
@@ -2063,7 +2063,8 @@ With a prefix argument, try to REVERSE the hunk."
 
 (defcustom diff-ask-before-revert-and-kill-hunk t
   "If non-nil, `diff-revert-and-kill-hunk' will ask for confirmation."
-  :type 'boolean)
+  :type 'boolean
+  :version "31.1")
 
 (defun diff-revert-and-kill-hunk ()
   "Reverse-apply and then kill the hunk at point.  Save changed buffer.
@@ -2076,7 +2077,7 @@ to permanently drop changes you didn't intend, or no longer want.
 
 This is a destructive operation, so by default, this command asks you to
 confirm you really want to reverse-apply and kill the hunk.  You can
-customize `diff-ask-before-revert-and-kill-hunk' to change that."
+customize `diff-ask-before-revert-and-kill-hunk' to control that."
   (interactive)
   (when (or (not diff-ask-before-revert-and-kill-hunk)
             (yes-or-no-p "Really reverse-apply and kill this hunk?"))
@@ -2086,11 +2087,11 @@ customize `diff-ask-before-revert-and-kill-hunk' to change that."
 
 (defun diff-apply-buffer (&optional beg end reverse)
   "Apply the diff in the entire diff buffer.
-When applying all hunks was successful, then save the changed buffers.
+If applying all hunks succeeds, save the changed buffers.
 When called from Lisp with optional arguments, restrict the application
-to hunks lying between BEG and END, and reverse-apply when REVERSE is
-non-nil.  Returns nil if buffers were saved, or the number of failed
-applications."
+to hunks lying between BEG and END, and reverse-apply them when REVERSE is
+non-nil.  Returns nil if buffers were successfully modified and saved, or
+the number of failed hunk applications otherwise."
   (interactive)
   (let ((buffer-edits nil)
         (failures 0)