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.

1 files changed, 11 insertions, 9 deletions

diff --git a/lisp/emacs-lisp/ert.el b/lisp/emacs-lisp/ert.el
index 6a665c8181d..2d96e5ce5a9 100644
--- 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