More doc fixes.

* lisp/minibuffer.el (read-file-name): Doc fix.

* character.c (Fcharacterp): Doc fix (Bug#12076).

* data.c (Findirect_variable): Doc fix (Bug#11040).

* editfns.c (Fsave_current_buffer): Doc fix (Bug#11542).

Fixes: debbugs:11542 debbugs:11040 debbugs:12076 debbugs:10881

6 files changed, 40 insertions, 18 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 8d27fc65185..606be46b118 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,7 @@
 2012-08-14  Chong Yidong  <cyd@gnu.org>
 
+        * minibuffer.el (read-file-name): Doc fix (Bug#10881).
+
         * emacs-lisp/regexp-opt.el (regexp-opt-charset): Doc fix
         (Bug#12085).
 
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 5c2c14d1fdb..cc2638d58de 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -2259,14 +2259,24 @@ such as making the current buffer visit no file in the case of
 (defun read-file-name (prompt &optional dir default-filename mustmatch initial predicate)
   "Read file name, prompting with PROMPT and completing in directory DIR.
 Value is not expanded---you must call `expand-file-name' yourself.
-Default name to DEFAULT-FILENAME if user exits the minibuffer with
-the same non-empty string that was inserted by this function.
- (If DEFAULT-FILENAME is omitted, the visited file name is used,
-  except that if INITIAL is specified, that combined with DIR is used.
-  If DEFAULT-FILENAME is a list of file names, the first file name is used.)
-If the user exits with an empty minibuffer, this function returns
-an empty string.  (This can only happen if the user erased the
-pre-inserted contents or if `insert-default-directory' is nil.)
+
+DIR is the directory to use for completing relative file names.
+It should be an absolute directory name, or nil (which means the
+current buffer's value of `default-directory').
+
+DEFAULT-FILENAME specifies the default file name to return if the
+user exits the minibuffer with the same non-empty string inserted
+by this function.  If DEFAULT-FILENAME is a string, that serves
+as the default.  If DEFAULT-FILENAME is a list of strings, the
+first string is the default.  If DEFAULT-FILENAME is omitted or
+nil, then if INITIAL is non-nil, the default is DIR combined with
+INITIAL; otherwise, if the current buffer is visiting a file,
+that file serves as the default; otherwise, the default is simply
+the string inserted into the minibuffer.
+
+If the user exits with an empty minibuffer, return an empty
+string.  (This happens only if the user erases the pre-inserted
+contents, or if `insert-default-directory' is nil.)
 
 Fourth arg MUSTMATCH can take the following values:
 - nil means that the user can exit with any input.
@@ -2283,10 +2293,10 @@ Fourth arg MUSTMATCH can take the following values:
 
 Fifth arg INITIAL specifies text to start with.
 
-If optional sixth arg PREDICATE is non-nil, possible completions and
-the resulting file name must satisfy (funcall PREDICATE NAME).
-DIR should be an absolute directory name.  It defaults to the value of
-`default-directory'.
+Sixth arg PREDICATE, if non-nil, should be a function of one
+argument; then a file name is considered an acceptable completion
+alternative only if PREDICATE returns non-nil with the file name
+as its argument.
 
 If this command was invoked with the mouse, use a graphical file
 dialog if `use-dialog-box' is non-nil, and the window system or X
diff --git a/src/ChangeLog b/src/ChangeLog
index 22f2ca18775..956d6922d2e 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,8 +1,13 @@
 2012-08-14  Chong Yidong  <cyd@gnu.org>
 
+        * character.c (Fcharacterp): Doc fix (Bug#12076).
+
+        * data.c (Findirect_variable): Doc fix (Bug#11040).
+
         * chartab.c (Fmap_char_table): Doc fix (Bug#12061).
 
         * editfns.c (Fformat): Doc fix (Bug#12059).
+        (Fsave_current_buffer): Doc fix (Bug#11542).
 
 2012-08-14  Barry OReilly  <gundaetiapo@gmail.com>  (tiny change)
 
diff --git a/src/character.c b/src/character.c
index bdb0eead740..b2acf36ec15 100644
--- a/src/character.c
+++ b/src/character.c
@@ -258,6 +258,9 @@ multibyte_char_to_unibyte_safe (int c)
 
 DEFUN ("characterp", Fcharacterp, Scharacterp, 1, 2, 0,
        doc: /* Return non-nil if OBJECT is a character.
+In Emacs Lisp, characters are represented by character codes, which
+are non-negative integers.  The function `max-char' returns the
+maximum character code.
 usage: (characterp OBJECT)  */)
   (Lisp_Object object, Lisp_Object ignore)
 {
diff --git a/src/data.c b/src/data.c
index 3e278e8bac3..d0ef5734abc 100644
--- a/src/data.c
+++ b/src/data.c
@@ -808,10 +808,12 @@ indirect_variable (struct Lisp_Symbol *symbol)
 
 DEFUN ("indirect-variable", Findirect_variable, Sindirect_variable, 1, 1, 0,
        doc: /* Return the variable at the end of OBJECT's variable chain.
-If OBJECT is a symbol, follow all variable indirections and return the final
-variable.  If OBJECT is not a symbol, just return it.
-Signal a cyclic-variable-indirection error if there is a loop in the
-variable chain of symbols.  */)
+If OBJECT is a symbol, follow its variable indirections (if any), and
+return the variable at the end of the chain of aliases.  See Info node
+`(elisp)Variable Aliases'.
+
+If OBJECT is not a symbol, just return it.  If there is a loop in the
+chain of aliases, signal a `cyclic-variable-indirection' error.  */)
   (Lisp_Object object)
 {
   if (SYMBOLP (object))
diff --git a/src/editfns.c b/src/editfns.c
index 806c80c1936..5ac012c8378 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -946,8 +946,8 @@ usage: (save-excursion &rest BODY)  */)
 }
 
 DEFUN ("save-current-buffer", Fsave_current_buffer, Ssave_current_buffer, 0, UNEVALLED, 0,
-       doc: /* Save the current buffer; execute BODY; restore the current buffer.
-Executes BODY just like `progn'.
+       doc: /* Record which buffer is current; execute BODY; make that buffer current.
+BODY is executed just like `progn'.
 usage: (save-current-buffer &rest BODY)  */)
   (Lisp_Object args)
 {