Doc updates re abbrev-expand-function

* doc/emacs/abbrevs.texi (Expanding Abbrevs): Update re abbrev-expand-function.

* doc/lispref/abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes.

* doc/lispref/functions.texi (Advising Functions): Standardize menu case.

* lisp/abbrev.el (abbrev-expand-functions, abbrev-expand-function)
(expand-abbrev, abbrev--default-expand): Doc fixes.

2 files changed, 14 insertions, 4 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 9d1e62baf8a..60b684fd8ad 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+2014-05-27  Glenn Morris  <rgm@gnu.org>
+
+        * abbrev.el (abbrev-expand-functions, abbrev-expand-function)
+        (expand-abbrev, abbrev--default-expand): Doc fixes.
+
 2014-05-26  Paul Eggert  <eggert@cs.ucla.edu>
 
         Include sources used to create macuvs.h.
diff --git a/lisp/abbrev.el b/lisp/abbrev.el
index 43b6a5583ee..9e11adadfc0 100644
--- a/lisp/abbrev.el
+++ b/lisp/abbrev.el
@@ -824,23 +824,28 @@ see `define-abbrev' for details."
     value))
 
 (defvar abbrev-expand-functions nil
-  "Wrapper hook around `expand-abbrev'.")
+  "Wrapper hook around `abbrev--default-expand'.")
 (make-obsolete-variable 'abbrev-expand-functions 'abbrev-expand-function "24.4")
 
 (defvar abbrev-expand-function #'abbrev--default-expand
-  "Function to perform abbrev expansion.
+  "Function that `expand-abbrev' uses to perform abbrev expansion.
 Takes no argument and should return the abbrev symbol if expansion took place.")
 
 (defun expand-abbrev ()
   "Expand the abbrev before point, if there is an abbrev there.
 Effective when explicitly called even when `abbrev-mode' is nil.
-Returns the abbrev symbol, if expansion took place.  (The actual
-return value is that of `abbrev-insert'.)"
+Before doing anything else, runs `pre-abbrev-expand-hook'.
+Calls `abbrev-expand-function' with no argument to do the work,
+and returns whatever it does.  (This should be the abbrev symbol
+if expansion occurred, else nil.)"
   (interactive)
   (run-hooks 'pre-abbrev-expand-hook)
   (funcall abbrev-expand-function))
 
 (defun abbrev--default-expand ()
+  "Default function to use for `abbrev-expand-function'.
+This respects the wrapper hook `abbrev-expand-functions'.
+Calls `abbrev-insert' to insert any expansion, and returns what it does."
   (with-wrapper-hook abbrev-expand-functions ()
     (pcase-let ((`(,sym ,name ,wordstart ,wordend) (abbrev--before-point)))
       (when sym