Hey all,
This short series is a follow-up to my last series. It could have been
longer, but I think this is a good point to get some feedback on a few
points.
As background, something I wondered about and the answer seems to be No
is, can we automatically take things like:
@pytest.mark.buildconfigspec('cmd_button')
and get some nice output? Since we can't that limits the value,
possibly, of generating some documentation.
First, as this series shows, is there value in documenting tests which
do not require additional configuration? We have some tests with no
comments and some that are fully commented, but at the end of the day
when trying to run these tests, pytest will already say helpful things
like not being supported on a given platform, or not run because
something isn't enabled in the build. Spelling that out in generated
documentation would require duplication of work.
Second, is there value in documenting arguments? Especially ones like
"ubman" that are just required and always present?
Third, should we document internal functions too, or just the tests? I
would be inclined to say no unless they're expected to be re-used. The
test_net functions to bring up the networking are an example that of
reuse that should be documented for example.
--
Tom
