Commit 9fc9988d authored by Eli Zaretskii's avatar Eli Zaretskii

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.
parent c14a1d45
......@@ -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
@code{filter-buffer-substring-functions}, and the obsolete variable
@code{filter-buffer-substring-functions} (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.
......
......@@ -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)))
......
......@@ -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.
......
......@@ -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)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment