Add the new macro with-suppressed-warnings

* lisp/emacs-lisp/byte-run.el (with-suppressed-warnings): New macro.

* doc/lispref/compile.texi (Compiler Errors): Document
with-suppressed-warnings and deemphasise with-no-warnings
slightly.

* lisp/emacs-lisp/bytecomp.el (byte-compile--suppressed-warnings):
New internal variable.
(byte-compile-warning-enabled-p): Heed
byte-compile--suppressed-warnings, bound via with-suppressed-warnings.
(byte-compile-initial-macro-environment): Provide a macro
expansion of with-suppressed-warnings.
(byte-compile-file-form-with-suppressed-warnings): New byte hunk
handler for the suppressed symbol machinery.
(byte-compile-suppressed-warnings): Ditto for the byteop.
(byte-compile-file-form-defmumble): Ditto.
(byte-compile-form, byte-compile-normal-call)
(byte-compile-normal-call, byte-compile-variable-ref)
(byte-compile-set-default, byte-compile-variable-set)
(byte-compile-function-form, byte-compile-set-default)
(byte-compile-warn-obsolete, byte-compile--declare-var): Pass the
symbol being warned in to byte-compile-warning-enabled-p.

* test/lisp/emacs-lisp/bytecomp-tests.el (test-suppression): New
function.
(bytecomp-test--with-suppressed-warnings): Tests.

1 files changed, 22 insertions, 4 deletions

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index d9db55e22cd..4ff0e1c91e4 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