[Emacs-diffs] scratch/with-suppressed-warnings 106afbc 1/4: Document with-suppressed-warnings

[Lars Ingebrigtsen]

branch: scratch/with-suppressed-warnings
commit 106afbcb82402f324fd15895f373497ec9ea3d08
Author: Lars Ingebrigtsen <address@hidden>
Commit: Lars Ingebrigtsen <address@hidden>

    Document with-suppressed-warnings
---
 doc/lispref/compile.texi | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index d9db55e..4ff0e1c 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -505,8 +505,25 @@ current lexical scope, or file if at top-level.)  
@xref{Defining
 Variables}.
 @end itemize
 
-  You can also suppress any and all compiler warnings within a certain
-expression using the construct @code{with-no-warnings}:
+  You can also suppress compiler warnings within a certain expression
+using the @code{with-suppressed-warnings} macro:
+
+@defspec with-suppressed-warnings warnings body@dots{}
+In execution, this is equivalent to @code{(progn @var{body}...)}, but
+the compiler does not issue warnings for the specified conditions in
+@var{body}.  @var{warnings} is an associative list of warning symbols
+and function/variable symbols they apply to.  For instance, if you
+wish to call an obsolete function called @code{foo}, but want to
+suppress the compilation warning, say:
+
+@lisp
+(with-suppressed-warnings ((obsolete foo))
+  (foo ...))
+@end lisp
+@end defspec
+
+For more coarse-grained suppression of compiler warnings, you can use
+the @code{with-no-warnings} construct:
 
 @c This is implemented with a defun, but conceptually it is
 @c a special form.
@@ -516,8 +533,9 @@ In execution, this is equivalent to @code{(progn 
@var{body}...)},
 but the compiler does not issue warnings for anything that occurs
 inside @var{body}.
 
-We recommend that you use this construct around the smallest
-possible piece of code, to avoid missing possible warnings other than
+We recommend that you use @code{with-suppressed-warnings} instead, but
+if you do use this construct, that you use it around the smallest
+possible piece of code to avoid missing possible warnings other than
 one you intend to suppress.
 @end defspec