Rename doctest_collect

[catch22]

We should perhaps rename doctest_collect to something else since the name still reflects my original implementation which collected tests but did not run them (#bikeshedding 😄).

[cbm755]

I tried to think about this during some recent changes but I didn't really come up with anything better. How about you?

[catch22]

Warning: Much bike-shedding follows. Perhaps un-confusing the terminology might have some value, though.

Consider the following terminology:

• a target is the name of a function/class/directory/file (anything that doctest and doctest_collect can be run on). it contains one or more units.
• a unit is something that holds a docstring (function/class/texinfo). it consists of one or more tests, which are executed one after the other in the same namespace.
• a test consists of source code, expected, modifiers, etc.

(Currently, we do not have a name for what I call "target", but we use the term "target" instead of "unit" in the source code.)

We could then rename:

• doctest_collect => doctest_targets (and change it to accept a list of targets; the only reason this is not part of the doctest implementation is that it calls itself recursively)
• doctest_run_docstring => doctest_parse_docstring (and do not call the below method from it)
• doctest_run_tests => doctest_run_unit_tests (this one does not display any output)

[cbm755]

This sounds good overall.

1. help doctest refers to "targets"; this does not change (right?)
2. I'm not keen on the name doctest_run_unit_tests b/c "unit test" has a well-known meaning.
3. "a unit is something that holds a docstring (function/class/texinfo)." I assume you mean "class method" (rather than class).
4. but if so, how does unit differ from "docstring"?

[catch22]

1. Let's brainstorm a bit more on target/unit/test. In unit testing, a "test case" has one or more "tests" or "test methods". These may be called individually and in isolation, i.e. there is no well-defined order among the different tests.
   In contrast, for us all the tests in a docstring are run sequentially with shared state - so the smallest testable unit is the list of tests in the docstring. That's why I thought "unit" might be an appropriate term.
   (We currently call this a "target". But a "target" sounds to me more like something that you run doctest on, e.g. a file name, directory name, function name, texinfo filename, etc.)
   I'm not 100% happy about the term "unit" though, because in unit testing terminology the "unit" is what is being tested, whereas here I am using it for a smallest collection of tests. Now if we called "unit" a "docstring" instead... (see point 4).

2. I think it doesn't disagree with the well-known meaning, but I agree that it might still be misleading so we should use a different name.

3. We test both the general class help (output of help class) and the help of the methods.

4. I was thinking of the "unit" as the semantical entity and of the "docstring" as an implementation detail.

[cbm755]

2. Agree

3. Yes but my point is class method would be a 'unit' but a class cannot. Rather a class would have many units.

From user PoV, targets and tests are tangible and understandable. Don't think user needs to care about 'units'. Since 'unit' is often a target, what if we try to use 'target'? i.e.,doctest_run_target_tests.

In our private code we might use "target" in a technical implementation sense of "thing with one docstring and no subtargets".

Or we can call that 'unit', as long as user doesn't see it ;-)

[catch22]

3. I agree -- I was thinking there was one unit for the class' general docstring and the others for the docstrings of its class methods. Maybe unit should be called docstring after all. 😄

Let me mull this over some more. (Definitely not urgent for the next release.)