Doc updates for buffer-stale-function now applying to file buffers too

* doc/emacs/arevert-xtra.texi (Supporting additional buffers):
* doc/lispref/backups.texi (Reverting):
Update for buffer-stale-function also applying to file-buffers.

* lisp/autorevert.el (auto-revert-buffers):
* lisp/files.el (buffer-stale--default-function)
(buffer-stale-function, revert-buffer--default): Doc tweaks.

* etc/NEWS: Related edits.

doc/emacs/ChangeLog

@@ -3,6 +3,8 @@
 	* files.texi (Backup Names):
 	* arevert-xtra.texi (Supporting additional buffers):
 	Update for default values of some -function vars no longer being nil.
+	(Supporting additional buffers):
+	Update for buffer-stale-function also applying to file-buffers.
 
 2014-03-16  Dmitry Gutov  <dgutov@yandex.ru>
 

doc/emacs/arevert-xtra.texi

@@ -107,11 +107,11 @@ To support auto-reverting the buffer must first of all have a suitable
 @code{revert-buffer-function}.  @xref{Definition of
 revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}.
 
-In addition, it must have a @code{buffer-stale-function}.
+In addition, it must have a suitable @code{buffer-stale-function}.
 
 @c FIXME only defvar in all of doc/emacs!
 @defvar buffer-stale-function
-The value of this variable is a function to check whether a non-file
+The value of this variable is a function to check whether a
 buffer needs reverting.  This should be a function with one optional
 argument @var{noconfirm}.  The function should return non-@code{nil}
 if the buffer should be reverted.  The buffer is current when this
@@ -132,7 +132,7 @@ If you just want to automatically auto-revert every
 @code{auto-revert-interval} seconds (like the Buffer Menu), use:
 
 @example
-(set (make-local-variable 'buffer-stale-function)
+(setq-local buffer-stale-function
      #'(lambda (&optional noconfirm) 'fast))
 @end example
 

doc/lispref/ChangeLog

@@ -2,6 +2,8 @@
 
 	* backups.texi (Making Backups, Reverting):
 	Update for default values of some -function vars no longer being nil.
+	(Reverting): Update for buffer-stale-function
+	also applying to file-buffers.
 
 2014-03-25  Eli Zaretskii  <eliz@gnu.org>
 

doc/lispref/backups.texi

@@ -764,7 +764,9 @@ may or may not run this hook.
 @c FIXME?  Move this section from arevert-xtra to here?
 @defvar buffer-stale-function
 The value of this variable specifies a function to call to check
-whether a non-file buffer needs reverting
+whether a buffer needs reverting.  The default value only handles
+buffers that are visiting files, by checking their modification time.
+Buffers that are not visiting files require a custom function
 @iftex
 (@pxref{Supporting additional buffers,,, emacs-xtra,  Specialized Emacs Features}).
 @end iftex

etc/NEWS

@@ -1401,11 +1401,14 @@ argument, with the same interpretation as the returned value of
 
 ** Revert and Autorevert changes
 
-FIXME buffer-stale-function no longer just for non-file buffers?
++++
 *** The default values of `buffer-stale-function', `revert-buffer-function',
 and `revert-buffer-insert-file-contents-function' are no longer nil.
 Instead they default to functions that do what the nil value used to.
 
++++
+*** `buffer-stale-function' is now used for buffers visiting files too.
+
 ---
 *** If Emacs is compiled with file notification support, it uses notifications
 instead of checking file time stamps.  To disable this, set the user option

lisp/ChangeLog

@@ -1,3 +1,9 @@
+2014-04-04  Glenn Morris  <rgm@gnu.org>
+
+	* files.el (buffer-stale--default-function)
+	(buffer-stale-function, revert-buffer--default):
+	* autorevert.el (auto-revert-buffers): Doc tweaks.
+
 2014-04-03  Eli Zaretskii  <eliz@gnu.org>
 
 	* international/characters.el: Preload uni-mirrored.el.  (Bug#17169)

lisp/autorevert.el

@@ -672,7 +672,7 @@ Should `auto-revert-mode' be active in some buffers, those buffers
 are checked.
 
 Non-file buffers that have a custom `revert-buffer-function' and
-a `buffer-stale-function' are reverted either when Auto-Revert
+`buffer-stale-function' are reverted either when Auto-Revert
 Mode is active in that buffer, or when the variable
 `global-auto-revert-non-file-buffers' is non-nil and Global
 Auto-Revert Mode is active.

lisp/files.el

@@ -5349,13 +5349,16 @@ This should not be relied upon.")
   "Default function to use for `buffer-stale-function'.
 This function ignores its argument.
 This returns non-nil if the current buffer is visiting a readable file
-whose modification time does not match that of the buffer."
+whose modification time does not match that of the buffer.
+
+This function only handles buffers that are visiting files.
+Non-file buffers need a custom function"
   (and buffer-file-name
        (file-readable-p buffer-file-name)
        (not (verify-visited-file-modtime (current-buffer)))))
 
 (defvar buffer-stale-function #'buffer-stale--default-function
-  "Function to check whether a non-file buffer needs reverting.
+  "Function to check whether a buffer needs reverting.
 This should be a function with one optional argument NOCONFIRM.
 Auto Revert Mode passes t for NOCONFIRM.  The function should return
 non-nil if the buffer should be reverted.  A return value of
@@ -5450,7 +5453,10 @@ start and end.
 
 Calls `revert-buffer-insert-file-contents-function' to reread the
 contents of the visited file, with two arguments: the first is the file
-name, the second is non-nil if reading an auto-save file."
+name, the second is non-nil if reading an auto-save file.
+
+This function only handles buffers that are visiting files.
+Non-file buffers need a custom function."
   (with-current-buffer (or (buffer-base-buffer (current-buffer))
                            (current-buffer))
     (let* ((auto-save-p (and (not ignore-auto)