[Emacs-diffs] scratch/with-suppressed-warnings 087cfbc 3/4: Add a doc string to with-suppressed-warnings.

[Lars Ingebrigtsen]

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

    Add a doc string to with-suppressed-warnings.
---
 lisp/emacs-lisp/byte-run.el | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/lisp/emacs-lisp/byte-run.el b/lisp/emacs-lisp/byte-run.el
index e9a9e66..8fe3cca 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))