Allow write-contents-functions to short-circuit buffer save

Bug#28412

* lisp/files.el (basic-save-buffer): Re-arrange function so that
  write-contents-functions are run earlier. If they return non-nil,
  consider the buffer saved without requiring the buffer to be
  visiting a file.
  (save-some-buffers): This function should consider any buffer with a
  buffer-local value for write-contents-functions eligible for
  saving.
* test/lisp/files-tests.el (files-test-no-file-write-contents): New
  test.
* doc/lispref/files.texi (Saving Buffers): Mention in docs.
* etc/NEWS: And in NEWS.

1 files changed, 13 insertions, 5 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 901382fe9bd..6be998f0b2e 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -457,15 +457,23 @@ Even though this is not a normal hook, you can use @code{add-hook} and
 @defvar write-contents-functions
 This works just like @code{write-file-functions}, but it is intended
 for hooks that pertain to the buffer's contents, not to the particular
-visited file or its location.  Such hooks are usually set up by major
-modes, as buffer-local bindings for this variable.  This variable
-automatically becomes buffer-local whenever it is set; switching to a
-new major mode always resets this variable, but calling
-@code{set-visited-file-name} does not.
+visited file or its location, and can be used to create arbitrary save
+processes for buffers that aren't visiting files at all.  Such hooks
+are usually set up by major modes, as buffer-local bindings for this
+variable.  This variable automatically becomes buffer-local whenever
+it is set; switching to a new major mode always resets this variable,
+but calling @code{set-visited-file-name} does not.
 
 If any of the functions in this hook returns non-@code{nil}, the file
 is considered already written and the rest are not called and neither
 are the functions in @code{write-file-functions}.
+
+When using this hook to save buffers that are not visiting files (for
+instance, special-mode buffers), keep in mind that, if the function
+fails to save correctly and returns a @code{nil} value,
+@code{save-buffer} will go on to prompt the user for a file to save
+the buffer in.  If this is undesirable, consider having the function
+fail by raising an error.
 @end defvar
 
 @defopt before-save-hook