Re: Improving documentation for ert.el.

[Eli Zaretskii <eliz@gnu.org>]

> From: Richard Stallman <rms@gnu.org>
> Date: Sat, 10 Aug 2024 22:10:20 -0400
> 
> I started to write tests for `cond*', and found that the documentation
> in ert.el was unjelpful about how to run the test I had written.

ERT has its own manual, ert.info.  I suggest to read it when the doc
strings are insufficient, and definitely before you fall back on
reading the comments in ert.el -- that is NOT the primary source of
the documentation for users of ert.el.

> I read the comment at the beginning, which told me about
> `ert-run-tests-interactively'.  But what argument should I use?  The
> doc string of `ert-run-tests-interactively' referred me to
> `ert-select-tests'.

The ERT manual describes this command in "Running Tests
Interactively", and has a cross-reference to "Test Selectors" where
the argument is described.  But for most purposes, just accepting the
default argument of 't' (which means to run all tests) is what you
usually want.

> The doc string of `ert-select-tests' is abstract, and may be helpful
> for understanding how its code works, but it is no help for a user
> trying to see how to call `ert-run-tests-interactively' for any
> specific case.

The node "Test Selectors" in the ERT manual is more helpful, I think.

> I that the name defined with `ert-deftest' would have something to do
> with a name to specify, but was it the symbol itself or its value or
> somehing else?  Since the comments did not say, I tried them but
> confusion got in the way.  Eventually, after I started writing this, I
> tried again and that that name did work right when passed to
> `ert-run-tests-interactively'.
> 
> I think the documentation should say this very explicitly, at the top
> of the file, and in `ert-run-tests-interactively', and also in
> `ert-select-tests'.  This will be small compared with the size of
> ert.el.

I clarified some of the related doc strings and the ERT manual on the
emacs-30 branch.