Improving documentation for ert.el.

Improving documentation for ert.el.

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

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.

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 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.

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.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Improving documentation for ert.el.

[Eli Zaretskii]

> 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.