I did so, just moving up the description of delay-warning, and changing the beginning of the section to suggest using it, instead of directly `delayed-warnings-list'. That way, the low level details follow the function, for those interested in them.
From: Juanma Barranquero <
lekktu@gmail.com>
Date: Tue, 22 Oct 2019 16:36:17 +0200
Subject: [PATCH] * doc/lispref/display.texi: Document `delay-warning'
---
doc/lispref/display.texi | 12 +++++++++---
1 file changed, 9 insertions(+), 3 deletions(-)
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 82d9f1db61..8ba0327fbb 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -828,7 +828,13 @@ Delayed Warnings
Sometimes, you may wish to avoid showing a warning while a command is
running, and only show it only after the end of the command. You can
-use the variable @code{delayed-warnings-list} for this.
+use the function @code{delay-warning} for this.
+
+@defun delay-warning type message &optional level buffer-name
+This function is the delayed counterpart to @code{display-warning}
+(@pxref{Warning Basics}), and it is called with the same arguments.
+The warning message is queued into @code{delayed-warnings-list}.
+@end defun
@defvar delayed-warnings-list
The value of this variable is a list of warnings to be displayed after
@@ -840,8 +846,8 @@ Delayed Warnings
@noindent
with the same form, and the same meanings, as the argument list of
-@code{display-warning} (@pxref{Warning Basics}). Immediately after
-running @code{post-command-hook} (@pxref{Command Overview}), the Emacs
+@code{display-warning}. Immediately after running
+@code{post-command-hook} (@pxref{Command Overview}), the Emacs
command loop displays all the warnings specified by this variable,
then resets it to @code{nil}.
@end defvar
--
2.23.0.windows.1