From: Stefan Kangas <stefankangas@gmail.com>
Date: Sun, 23 Mar 2025 16:40:22 +0000 (+0100)
Subject: Improve docstring of should-error
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=fda2766c7acbb86bd8389660f85b5480ad678e56;p=emacs.git

Improve docstring of should-error

* lisp/emacs-lisp/ert.el (should-error): Improve docstring.

(cherry picked from commit c2c287b3252e2cd3223f2e2d0ef96f29e024b47b)
---

diff --git a/lisp/emacs-lisp/ert.el b/lisp/emacs-lisp/ert.el
index e2bb2703ac3..ebad69f301d 100644
--- a/lisp/emacs-lisp/ert.el
+++ b/lisp/emacs-lisp/ert.el
@@ -415,16 +415,23 @@ and aborts the current test as failed if it doesn't."
 (cl-defmacro should-error (form &rest keys &key type exclude-subtypes)
   "Evaluate FORM and check that it signals an error.
 
-The error signaled needs to match TYPE.  TYPE should be a list
-of condition names.  (It can also be a non-nil symbol, which is
-equivalent to a singleton list containing that symbol.)  If
-EXCLUDE-SUBTYPES is nil, the error matches TYPE if one of its
-condition names is an element of TYPE.  If EXCLUDE-SUBTYPES is
-non-nil, the error matches TYPE if it is an element of TYPE.
-
-If the error matches, returns (ERROR-SYMBOL . DATA) from the
-error.  If not, or if no error was signaled, abort the test as
-failed."
+If no error was signaled, abort the test as failed and
+return (ERROR-SYMBOL . DATA) from the error.
+
+You can also match specific errors using the KEYWORD-ARGS arguments,
+which is specified as keyword/argument pairs.  The following arguments
+are defined:
+
+:type TYPE -- If TYPE is non-nil, the error signaled needs to match
+TYPE.  TYPE should be a list of condition names.  It can also be a
+symbol, which is equivalent to a one-element list containing that
+symbol.
+
+:exclude-subtypes EXCLUDED -- If EXCLUDED is non-nil, the error matches
+TYPE only if it is an element of TYPE.  If nil (the default), the error
+matches TYPE if one of its condition names is an element of TYPE.
+
+\(fn FORM &rest KEYWORD-ARGS)"
   (declare (debug t))
   (unless type (setq type ''error))
   (ert--expand-should