Add a doc string to with-suppressed-warnings.

1 files changed, 21 insertions, 1 deletions

diff --git a/lisp/emacs-lisp/byte-run.el b/lisp/emacs-lisp/byte-run.el
index e9a9e668cc0..8fe3ccaec72 100644
--- a/lisp/emacs-lisp/byte-run.el
+++ b/lisp/emacs-lisp/byte-run.el
@@ -495,7 +495,27 @@ is enabled."
   (car (last body)))
 
 (defmacro with-suppressed-warnings (_warnings &rest body)
-  "Like `progn', but prevents compiler WARNINGS in BODY."
+  "Like `progn', but prevents compiler WARNINGS in BODY.
+
+WARNINGS is an associative list where the first element of each
+list is a warning type, and the rest of the elements in each list
+are symbols they apply to.  For instance, if you want to suppress
+byte compilation warnings about the two obsolete functions `foo'
+and `bar', say
+
+\(with-suppressed-warnings ((obsolete foo bar))
+   (foo)
+   (bar))
+
+The warnings that can be suppressed is a subset of the list in
+`byte-compile-warning-types'; see this for a fuller explanation
+of these warning types.  The types that can be suppressed with
+this macro is `free-vars', `callargs', `redefine', `obsolete',
+`interactive-only', `lexical', `mapcar', `constants' and
+`suspicious'.
+
+For the `mapcar' case, only the `mapcar' function can be used in
+the symbol list.  For `suspicious', only `set-buffer' can be used."
   (declare (debug (sexp &optional body)) (indent 1))
   ;; The implementation for the interpreter is basically trivial.
   `(progn ,@body))