Document 'vc-refresh-state'

* doc/emacs/maintaining.texi (Version Control): Document
'vc-refresh-state'.

* lisp/vc/vc-hooks.el (vc-refresh-state): Doc fix.

doc/emacs/maintaining.texi

@@ -47,6 +47,17 @@ variable @code{vc-handled-backends} to @code{nil}
 (@pxref{Customizing VC}).
 @end ifnottex
 
+@findex vc-refresh-state
+@findex vc-state-refresh
+  To update the VC state information for the file visited in the
+current buffer, use the command @code{vc-refresh-state}.  This command
+is useful when you perform version control commands outside Emacs
+(e.g., from the shell prompt), or if you put the buffer's file under a
+different version control system, or remove it from version control
+entirely.  A companion command @code{vc-state-refresh} does the same,
+but does not consider switching the version control system or removal
+from VC.
+
 @menu
 * Introduction to VC::  How version control works in general.
 * VC Mode Line::        How the mode line shows version control status.

etc/NEWS

@@ -321,8 +321,6 @@ the ordering of object keys by default.
 `json-pretty-print-buffer-ordered' pretty prints JSON objects with
 object keys sorted alphabetically.
 
-** You can recompute the VC state of a file buffer with `M-x vc-refresh-state'
-
 ** Prog mode has some support for multi-mode indentation.
 See `prog-indentation-context' and `prog-widen'.
 
@@ -733,6 +731,12 @@ Implemented for Bzr, Git, Hg.  As part of this change, the pre-existing
 
 *** The new command vc-region-history shows the log+diff of the active region.
 
++++
+*** You can refresh the VC state of a file buffer with `M-x vc-refresh-state'.
+This command is useful when you perform version control commands
+outside Emacs (e.g., from the shell prompt), or if you switch the VC
+back-end for the buffer's file, or remove it from version control.
+
 *** New option `vc-annotate-background-mode' controls whether
 the color range from `vc-annotate-color-map' is applied to the
 background or to the foreground.

lisp/vc/vc-hooks.el

@@ -791,7 +791,11 @@ current, and kill the buffer that visits the link."
   nil)
 
 (defun vc-refresh-state ()
-  "Activate or deactivate VC mode as appropriate."
+  "Refresh the VC state of the current buffer's file.
+
+This command is more thorough than `vc-state-refresh', in that it
+also supports switching a back-end or removing the file from VC.
+In the latter case, VC mode is deactivated for this buffer."
   (interactive)
   ;; Recompute whether file is version controlled,
   ;; if user has killed the buffer and revisited.