Re: master f6da1eed74: Properly report errors about unbound ERT test symbols.

Re: master f6da1eed74: Properly report errors about unbound ERT test symbols.

[Michael Albinus]

Philipp Stephani <p.stephani2@gmail.com> writes:

Hi Philipp,

> +*** Unbound test symbols now signal an 'ert-test-unbound' error.
> +This affects the 'ert-select-tests' function and its callers.

Shouldn't this be documented in doc/lispref/errors.texi and/or
doc/misc/ert.texi?

Best regards, Michael.

Re: master f6da1eed74: Properly report errors about unbound ERT test symbols.

[Philipp]

> Am 30.12.2021 um 17:34 schrieb Michael Albinus <michael.albinus@gmx.de>:
> 
> Philipp Stephani <p.stephani2@gmail.com> writes:
> 
> Hi Philipp,
> 
>> +*** Unbound test symbols now signal an 'ert-test-unbound' error.
>> +This affects the 'ert-select-tests' function and its callers.
> 
> Shouldn't this be documented in doc/lispref/errors.texi

That only documents the most common/important error symbol, and the new one is neither common nor important enough.

> and/or
> doc/misc/ert.texi?

That doesn't even document ert-select-tests.
I've mentioned it now in the docstring of ert-select-tests.

Re: master f6da1eed74: Properly report errors about unbound ERT test symbols.

[Michael Albinus]

Philipp <p.stephani2@gmail.com> writes:

Hi Philipp,

>>> +*** Unbound test symbols now signal an 'ert-test-unbound' error.
>>> +This affects the 'ert-select-tests' function and its callers.
>>
>> Shouldn't this be documented in doc/lispref/errors.texi
>
> That only documents the most common/important error symbol, and the new one is neither common nor important enough.

Good point.

>> and/or
>> doc/misc/ert.texi?
>
> That doesn't even document ert-select-tests.
> I've mentioned it now in the docstring of ert-select-tests.

Thanks!

In general, the ERT manual is very short, and it also doesn't document
the other error symbols as well (ert-test-failed and
ert-test-skipped). Sometimes, it would helped me to write some code
around ert functions, but likely there are not so many people doing it
like me.

So let it be ...

Best regards, Michael.

Re: master f6da1eed74: Properly report errors about unbound ERT test symbols.

[Philipp]

> Am 31.12.2021 um 14:45 schrieb Michael Albinus <michael.albinus@gmx.de>:
> 
> In general, the ERT manual is very short, and it also doesn't document
> the other error symbols as well (ert-test-failed and
> ert-test-skipped). Sometimes, it would helped me to write some code
> around ert functions, but likely there are not so many people doing it
> like me.

The manual states:

   Both ‘ert-run-tests-interactively’ and ‘ert-run-tests-batch’ are
implemented on top of the lower-level test handling code in the sections
of ‘ert.el’ labeled “Facilities for running a single test”, “Test
selectors”, and “Facilities for running a whole set of tests”.

   If you want to write code that works with ERT tests, you should take
a look at this lower-level code.  Symbols that start with ‘ert--’ are
internal to ERT, whereas those that start with ‘ert-’ are meant to be
usable by other code.  But there is no mature API yet.


I don't know what's missing before the API can be considered "mature", but adding some documentation about the API to the manual instead of referring to the source code would be a good first step.