Doc updates related to changes in revert-buffer function variables

* lisp/files.el (make-backup-file-name-function)
(make-backup-file-name, make-backup-file-name--default-function)
(make-backup-file-name-1, find-backup-file-name)
(revert-buffer-function, revert-buffer-insert-file-contents-function)
(buffer-stale--default-function, buffer-stale-function)
(before-revert-hook, after-revert-hook, revert-buffer-in-progress-p)
(revert-buffer, revert-buffer--default)
(revert-buffer-insert-file-contents--default-function):
Doc fixes related to defaults no longer being nil.
(make-backup-file-name-function): Bump :version.
Restore nil as a valid but deprecated custom type.

* etc/NEWS: Related edit.

3 files changed, 80 insertions, 37 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 81aebf09c37..32490aefd5c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1397,9 +1397,10 @@ argument, with the same interpretation as the returned value of
 
 ** Revert and Autorevert changes
 
-*** The default value of `revert-buffer-function' is no longer nil.
-Instead it defaults to a function that does what the nil value used to.
-The same applies for `revert-buffer-insert-file-contents-function'.
+*** The default values of `make-backup-file-name-function',
+`revert-buffer-function', `revert-buffer-insert-file-contents-function',
+and `buffer-stale-function' are no longer nil.  Instead they default
+to functions that do what the nil value used to.
 
 ---
 *** If Emacs is compiled with file notification support, it uses notifications
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5ea2d4483c4..ee7d61c7389 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,17 @@
+2014-04-03  Glenn Morris  <rgm@gnu.org>
+
+        * files.el (make-backup-file-name-function)
+        (make-backup-file-name, make-backup-file-name--default-function)
+        (make-backup-file-name-1, find-backup-file-name)
+        (revert-buffer-function, revert-buffer-insert-file-contents-function)
+        (buffer-stale--default-function, buffer-stale-function)
+        (before-revert-hook, after-revert-hook, revert-buffer-in-progress-p)
+        (revert-buffer, revert-buffer--default)
+        (revert-buffer-insert-file-contents--default-function):
+        Doc fixes related to defaults no longer being nil.
+        (make-backup-file-name-function): Bump :version.
+        Restore nil as a valid but deprecated custom type.
+
 2014-04-03  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * progmodes/perl-mode.el (perl-syntax-propertize-function): Handle $'
diff --git a/lisp/files.el b/lisp/files.el
index 6d0be9234e6..d5c6028ff47 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -4215,15 +4215,22 @@ FILENAME defaults to `buffer-file-name'."
 
 (defcustom make-backup-file-name-function
   #'make-backup-file-name--default-function
-  "A function to use instead of the default `make-backup-file-name'.
+  "A function that `make-backup-file-name' uses to create backup file names.
+The function receives a single argument, the original file name.
 
-This could be buffer-local to do something special for specific
-files.  If you define it, you may need to change `backup-file-name-p'
-and `file-name-sans-versions' too.
+If you change this, you may need to change `backup-file-name-p' and
+`file-name-sans-versions' too.
+
+You could make this buffer-local to do something special for specific files.
+
+For historical reasons, a value of nil means to use the default function.
+This should not be relied upon.
 
 See also `backup-directory-alist'."
+  :version "24.4"     ; nil -> make-backup-file-name--default-function
   :group 'backup
-  :type '(function :tag "Your function"))
+  :type '(choice (const :tag "Deprecated way to get the default function" nil)
+                 (function :tag "Function")))
 
 (defcustom backup-directory-alist nil
   "Alist of filename patterns and backup directory names.
@@ -4280,20 +4287,17 @@ Checks for files in `temporary-file-directory',
 
 (defun make-backup-file-name (file)
   "Create the non-numeric backup file name for FILE.
-Normally this will just be the file's name with `~' appended.
-Customization hooks are provided as follows.
-
-The value of `make-backup-file-name-function' should be a function which
-will be called with FILE as its argument; the resulting name is used.
-
-By default, a match for FILE is sought in `backup-directory-alist'; see
-the documentation of that variable.  If the directory for the backup
-doesn't exist, it is created."
+This calls the function that `make-backup-file-name-function' specifies,
+with a single argument FILE."
   (funcall (or make-backup-file-name-function
                #'make-backup-file-name--default-function)
            file))
 
 (defun make-backup-file-name--default-function (file)
+  "Default function for `make-backup-file-name'.
+Normally this just returns FILE's name with `~' appended.
+It searches for a match for FILE in `backup-directory-alist'.
+If the directory for the backup doesn't exist, it is created."
   (if (and (eq system-type 'ms-dos)
            (not (msdos-long-file-names)))
       (let ((fn (file-name-nondirectory file)))
@@ -4305,7 +4309,8 @@ doesn't exist, it is created."
     (concat (make-backup-file-name-1 file) "~")))
 
 (defun make-backup-file-name-1 (file)
-  "Subroutine of `make-backup-file-name' and `find-backup-file-name'."
+  "Subroutine of `make-backup-file-name--default-function'.
+The function `find-backup-file-name' also uses this."
   (let ((alist backup-directory-alist)
         elt backup-directory abs-backup-directory)
     (while alist
@@ -4382,8 +4387,8 @@ the index in the name where the version number begins."
 Value is a list whose car is the name for the backup file
 and whose cdr is a list of old versions to consider deleting now.
 If the value is nil, don't make a backup.
-Uses `backup-directory-alist' in the same way as does
-`make-backup-file-name'."
+Uses `backup-directory-alist' in the same way as
+`make-backup-file-name--default-function' does."
   (let ((handler (find-file-name-handler fn 'find-backup-file-name)))
     ;; Run a handler for this function so that ange-ftp can refuse to do it.
     (if handler
@@ -5319,22 +5324,32 @@ comparison."
 
 (put 'revert-buffer-function 'permanent-local t)
 (defvar revert-buffer-function #'revert-buffer--default
-  "Function to use to revert this buffer, or nil to do the default.
+  "Function to use to revert this buffer.
 The function receives two arguments IGNORE-AUTO and NOCONFIRM,
 which are the arguments that `revert-buffer' received.
 It also has access to the `preserve-modes' argument of `revert-buffer'
-via the `revert-buffer-preserve-modes' dynamic variable.")
+via the `revert-buffer-preserve-modes' dynamic variable.
+
+For historical reasons, a value of nil means to use the default function.
+This should not be relied upon.")
 
 (put 'revert-buffer-insert-file-contents-function 'permanent-local t)
 (defvar revert-buffer-insert-file-contents-function
   #'revert-buffer-insert-file-contents--default-function
   "Function to use to insert contents when reverting this buffer.
-Gets two args, first the nominal file name to use,
-and second, t if reading the auto-save file.
+The function receives two arguments: the first the nominal file name to use;
+the second is t if reading the auto-save file.
 
-The function you specify is responsible for updating (or preserving) point.")
+The function is responsible for updating (or preserving) point.
+
+For historical reasons, a value of nil means to use the default function.
+This should not be relied upon.")
 
 (defun buffer-stale--default-function (&optional _noconfirm)
+  "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."
   (and buffer-file-name
        (file-readable-p buffer-file-name)
        (not (verify-visited-file-modtime (current-buffer)))))
@@ -5353,13 +5368,16 @@ non-nil if the buffer is going to be reverted without asking the
 user.  In such situations, one has to be careful with potentially
 time consuming operations.
 
+For historical reasons, a value of nil means to use the default function.
+This should not be relied upon.
+
 For more information on how this variable is used by Auto Revert mode,
 see Info node `(emacs)Supporting additional buffers'.")
 
 (defvar before-revert-hook nil
   "Normal hook for `revert-buffer' to run before reverting.
-If `revert-buffer-function' is used to override the normal revert
-mechanism, this hook is not used.")
+The function `revert-buffer--default' runs this.
+A customized `revert-buffer-function' need not run this hook.")
 
 (defvar after-revert-hook nil
   "Normal hook for `revert-buffer' to run after reverting.
@@ -5367,12 +5385,11 @@ Note that the hook value that it runs is the value that was in effect
 before reverting; that makes a difference if you have buffer-local
 hook functions.
 
-If `revert-buffer-function' is used to override the normal revert
-mechanism, this hook is not used.")
+The function `revert-buffer--default' runs this.
+A customized `revert-buffer-function' need not run this hook.")
 
 (defvar revert-buffer-in-progress-p nil
-  "Non-nil if a `revert-buffer' operation is in progress, nil otherwise.
-This is true even if a `revert-buffer-function' is being used.")
+  "Non-nil if a `revert-buffer' operation is in progress, nil otherwise.")
 
 (defvar revert-buffer-internal-hook)
 
@@ -5409,12 +5426,10 @@ the files modes.  Normally we reinitialize them using `normal-mode'.
 
 This function binds `revert-buffer-in-progress-p' non-nil while it operates.
 
-If the value of `revert-buffer-function' is non-nil, it is called to
-do all the work for this command.  Otherwise, the hooks
-`before-revert-hook' and `after-revert-hook' are run at the beginning
-and the end, and if `revert-buffer-insert-file-contents-function' is
-non-nil, it is called instead of rereading visited file contents."
-
+This function calls the function that `revert-buffer-function' specifies
+to do the work, with arguments IGNORE-AUTO and NOCONFIRM.
+The default function runs the hooks `before-revert-hook' and
+`after-revert-hook'."
   ;; I admit it's odd to reverse the sense of the prefix argument, but
   ;; there is a lot of code out there which assumes that the first
   ;; argument should be t to avoid consulting the auto-save file, and
@@ -5426,7 +5441,16 @@ non-nil, it is called instead of rereading visited file contents."
         (revert-buffer-preserve-modes preserve-modes))
     (funcall (or revert-buffer-function #'revert-buffer--default)
              ignore-auto noconfirm)))
+
 (defun revert-buffer--default (ignore-auto noconfirm)
+  "Default function for `revert-buffer'.
+The arguments IGNORE-AUTO and NOCONFIRM are as described for `revert-buffer'.
+Runs the hooks `before-revert-hook' and `after-revert-hook' at the
+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."
   (with-current-buffer (or (buffer-base-buffer (current-buffer))
                            (current-buffer))
     (let* ((auto-save-p (and (not ignore-auto)
@@ -5480,6 +5504,10 @@ non-nil, it is called instead of rereading visited file contents."
              t)))))
 
 (defun revert-buffer-insert-file-contents--default-function (file-name auto-save-p)
+  "Default function for `revert-buffer-insert-file-contents-function'.
+The function `revert-buffer--default' calls this.
+FILE-NAME is the name of the file.  AUTO-SAVE-P is non-nil if this is
+an auto-save file."
   (cond
    ((not (file-exists-p file-name))
     (error (if buffer-file-number