[Emacs-diffs] emacs-25 9fc9988: Improve documentation of 'expand-abbrev' and wrapper hooks

[Eli Zaretskii]

branch: emacs-25
commit 9fc9988d4d08028fb37c588f5e0483ac85b713d3
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of 'expand-abbrev' and wrapper hooks
    
    * lisp/simple.el (filter-buffer-substring-functions)
    (buffer-substring--filter): Add a link to 'with-wrapper-hook' as
    the place to look for documentation of wrapper hooks.
    * lisp/minibuffer.el (completion-in-region-functions)
    (completion--in-region): Add a link to 'with-wrapper-hook' as the
    place to look for documentation of wrapper hooks.
    * lisp/abbrev.el (expand-abbrev, abbrev--default-expand): Clarify
    the doc strings.  (Bug#24540)
    
    * doc/lispref/text.texi (Buffer Contents): Mention
    'with-wrapper-hook's doc string as the place to learn about that
    obsolete facility.
---
 doc/lispref/text.texi |    4 +++-
 lisp/abbrev.el        |    9 +++++----
 lisp/minibuffer.el    |    6 ++++--
 lisp/simple.el        |    6 ++++--
 4 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 0445d68..f37f75f 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -232,7 +232,9 @@ using a function specified by the variable
 @code{filter-buffer-substring-function}, and returns the result.
 
 The default filter function consults the obsolete wrapper hook
address@hidden, and the obsolete variable
address@hidden (see the documentation string
+of the macro @code{with-wrapper-hook} for the details about this
+obsolete facility), and the obsolete variable
 @code{buffer-substring-filters}.  If both of these are @code{nil}, it
 returns the unaltered text from the buffer, i.e., what
 @code{buffer-substring} would return.
diff --git a/lisp/abbrev.el b/lisp/abbrev.el
index d181d97..8c4f6eb 100644
--- a/lisp/abbrev.el
+++ b/lisp/abbrev.el
@@ -837,16 +837,17 @@ Takes no argument and should return the abbrev symbol if 
expansion took place.")
   "Expand the abbrev before point, if there is an abbrev there.
 Effective when explicitly called even when `abbrev-mode' is nil.
 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.)"
+Calls the value of `abbrev-expand-function' with no argument to do
+the work, and returns whatever it does.  (That return value 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'.
+This also respects the obsolete wrapper hook `abbrev-expand-functions'.
+\(See `with-wrapper-hook' for details about wrapper hooks.)
 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)))
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 1ee05d3..c7f7c41 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -1925,7 +1925,8 @@ variables.")
   (exit-minibuffer))
 
 (defvar completion-in-region-functions nil
-  "Wrapper hook around `completion--in-region'.")
+  "Wrapper hook around `completion--in-region'.
+\(See `with-wrapper-hook' for details about wrapper hooks.)")
 (make-obsolete-variable 'completion-in-region-functions
                         'completion-in-region-function "24.4")
 
@@ -1969,7 +1970,8 @@ if there was no valid completion, else t."
 (defun completion--in-region (start end collection &optional predicate)
   "Default function to use for `completion-in-region-function'.
 Its arguments and return value are as specified for `completion-in-region'.
-This respects the wrapper hook `completion-in-region-functions'."
+Also respects the obsolete wrapper hook `completion-in-region-functions'.
+\(See `with-wrapper-hook' for details about wrapper hooks.)"
   (with-wrapper-hook
       ;; FIXME: Maybe we should use this hook to provide a "display
       ;; completions" operation as well.
diff --git a/lisp/simple.el b/lisp/simple.el
index 5dbaebb..c7d3b2e 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -4009,7 +4009,8 @@ These commands include \\[set-mark-command] and 
\\[start-kbd-macro]."
 
 
 (defvar filter-buffer-substring-functions nil
-  "This variable is a wrapper hook around `buffer-substring--filter'.")
+  "This variable is a wrapper hook around `buffer-substring--filter'.
+\(See `with-wrapper-hook' for details about wrapper hooks.)")
 (make-obsolete-variable 'filter-buffer-substring-functions
                         'filter-buffer-substring-function "24.4")
 
@@ -4050,7 +4051,8 @@ that are special to a buffer, and should not be copied 
into other buffers."
 (defun buffer-substring--filter (beg end &optional delete)
   "Default function to use for `filter-buffer-substring-function'.
 Its arguments and return value are as specified for `filter-buffer-substring'.
-This respects the wrapper hook `filter-buffer-substring-functions',
+Also respects the obsolete wrapper hook `filter-buffer-substring-functions'
+\(see `with-wrapper-hook' for details about wrapper hooks),
 and the abnormal hook `buffer-substring-filters'.
 No filtering is done unless a hook says to."
   (with-wrapper-hook filter-buffer-substring-functions (beg end delete)