Improve documentation of 'auto-coding-functions'

* doc/lispref/nonascii.texi (Default Coding Systems): Clarify
that the functions in 'auto-coding-functions' are called both
for decoding and for encoding.

* lisp/international/mule.el (auto-coding-functions): Doc fix.

2 files changed, 15 insertions, 7 deletions

diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index 66d12033d82..d58041b279b 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -1632,11 +1632,16 @@ coding system for a file based on its undecoded contents.
 
 Each function in this list should be written to look at text in the
 current buffer, but should not modify it in any way.  The buffer will
-contain undecoded text of parts of the file.  Each function should
-take one argument, @var{size}, which tells it how many characters to
-look at, starting from point.  If the function succeeds in determining
-a coding system for the file, it should return that coding system.
-Otherwise, it should return @code{nil}.
+contain the text of parts of the file.  Each function should take one
+argument, @var{size}, which tells it how many characters to look at,
+starting from point.  If the function succeeds in determining a coding
+system for the file, it should return that coding system.  Otherwise,
+it should return @code{nil}.
+
+The functions in this list could be called either when the file is
+visited and Emacs wants to decode its contents, and/or when the file's
+buffer is about to be saved and Emacs wants to determine how to encode
+its contents.
 
 If a file has a @samp{coding:} tag, that takes precedence, so these
 functions won't be called.
diff --git a/lisp/international/mule.el b/lisp/international/mule.el
index 58fdd28243a..cc0658dc3f4 100644
--- a/lisp/international/mule.el
+++ b/lisp/international/mule.el
@@ -1851,9 +1851,12 @@ or nil."
 
 Each function in this list should be written to operate on the
 current buffer, but should not modify it in any way.  The buffer
-will contain undecoded text of parts of the file.  Each function
+will contain the text of parts of the file.  Each function
 should take one argument, SIZE, which says how many characters
-\(starting from point) it should look at.
+\(starting from point) it should look at.  The function might be
+called both when the file is visited and Emacs wants to decode
+its contents, and when the file's buffer is about to be saved
+and Emacs wants to determine how to encode its contents.
 
 If one of these functions succeeds in determining a coding
 system, it should return that coding system.  Otherwise, it