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

doc/emacs/files.texi

@@ -1675,6 +1675,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
@@ -1684,18 +1685,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

etc/NEWS

@@ -365,8 +365,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
 

lisp/vc/diff-mode.el

@@ -2055,7 +2055,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.
@@ -2068,7 +2069,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?"))
@@ -2078,11 +2079,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)