Improve documentation of ERT

* doc/misc/ert.texi (Running Tests Interactively)
(Test Selectors):
* lisp/emacs-lisp/ert.el (ert-select-tests)
(ert-run-tests-interactively, ert-run-tests-batch): Improve and
clarify the documentation of the main ERT functions.

(cherry picked from commit 4f3e8c3b4ed7b4d12fca9370e84e91b4b3379c7c)

diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi
index 109dbd0f0ceea450ebd28f9249b3cee4f4b83f7b..1ac0378148b2a2299693bc60c03b16782a5d3e17 100644 (file)
--- a/doc/misc/ert.texi
+++ b/doc/misc/ert.texi
@@ -203,9 +203,12 @@ different Emacs versions.
 @cindex interactive testing
 
 @findex ert
+@findex ert-run-tests-interactively
 You can run the tests that are currently defined in your Emacs with the
-command @kbd{M-x ert @key{RET} t @key{RET}}.  (For an explanation of the
-@code{t} argument, @pxref{Test Selectors}.)  ERT will pop up a new
+command @kbd{M-x ert @key{RET} t @key{RET}} (which is an alias of
+@code{ert-run-tests-interactively}).  The @code{t} argument means to run
+all the defined tests, see @ref{Test Selectors}, which also explains how
+to run only some specific part of the tests.  ERT will pop up a new
 buffer, the ERT results buffer, showing the results of the tests run.
 It looks like this:
 
@@ -474,7 +477,7 @@ to Common Lisp's type specifier syntax:
 @item @code{:failed} and @code{:passed} select tests according to their most recent result.
 @item @code{:expected}, @code{:unexpected} select tests according to their most recent result.
 @item A string is a regular expression that selects all tests with matching names.
-@item A test (i.e., an object of @code{ert-test} data type) selects that test.
+@item A test (i.e., an object of @code{ert-test} data type, see its doc string for details) selects that test.
 @item A symbol selects the test that the symbol names.
 @item @code{(member @var{tests}...)} selects the elements of
 @var{tests}, a list of tests or symbols naming tests.

diff --git a/lisp/emacs-lisp/ert.el b/lisp/emacs-lisp/ert.el
index 2a28dd6f3d2a51c5040e7879d454599c1c973bf7..93dcfc39d1b453dbb1ba52db6e454bfaa78f9ff1 100644 (file)
--- a/lisp/emacs-lisp/ert.el
+++ b/lisp/emacs-lisp/ert.el
@@ -932,14 +932,14 @@ of tests, or t, which refers to all tests named by symbols in `obarray'.
 Valid SELECTORs:
 
 nil  -- Selects the empty set.
-t    -- Selects UNIVERSE.
+t    -- Selects all of UNIVERSE.  If UNIVERSE is t, selects all tests.
 :new -- Selects all tests that have not been run yet.
 :failed, :passed       -- Select tests according to their most recent result.
 :expected, :unexpected -- Select tests according to their most recent result.
 a string -- A regular expression selecting all tests with matching names.
-a test   -- (i.e., an object of the ert-test data-type) Selects that test.
-a symbol -- Selects the test that the symbol names, signals an
-    `ert-test-unbound' error if none.
+a test   -- (i.e., an object of the `ert-test' data-type) Selects that test.
+a symbol -- Selects the test named by the symbol, signals an
+    `ert-test-unbound' error if no such test.
 \(member TESTS...) -- Selects the elements of TESTS, a list of tests
     or symbols naming tests.
 \(eql TEST) -- Selects TEST, a test or a symbol naming a test.
@@ -1375,10 +1375,10 @@ RESULT must be an `ert-test-result-with-condition'."
 (defun ert-run-tests-batch (&optional selector)
   "Run the tests specified by SELECTOR, printing results to the terminal.
 
-SELECTOR works as described in `ert-select-tests', except if
-SELECTOR is nil, in which case all tests rather than none will be
-run; this makes the command line \"emacs -batch -l my-tests.el -f
-ert-run-tests-batch-and-exit\" useful.
+SELECTOR selects which tests to run as described in `ert-select-tests' when
+called with its second argument t, except if SELECTOR is nil, in which case
+all tests rather than none will be run; this makes the command line
+ \"emacs -batch -l my-tests.el -f ert-run-tests-batch-and-exit\" useful.
 
 Returns the stats object."
   (unless selector (setq selector 't))
@@ -2240,7 +2240,9 @@ STATS is the stats object; LISTENER is the results listener."
 (defun ert-run-tests-interactively (selector)
   "Run the tests specified by SELECTOR and display the results in a buffer.
 
-SELECTOR works as described in `ert-select-tests'."
+SELECTOR selects which tests to run as described in `ert-select-tests'
+when called with its second argument t.  Interactively, prompt for
+SELECTOR; the default t means run all the defined tests."
   (interactive
    (list (let ((default (if ert--selector-history
                             ;; Can't use `first' here as this form is