On Thu, Oct 22, 2020 at 09:26:45AM -0700, Daniel Latypov wrote:
On Thu, Oct 22, 2020 at 8:06 AM Andy Shevchenko andriy.shevchenko@linux.intel.com wrote:
On Wed, Oct 21, 2020 at 10:47:50AM -0700, Daniel Latypov wrote:
...
You need to put detailed comments in the code to have it as real example how to create the KUnit test. But hey, it will mean that documentation sucks. So,
Out of curiosity
- By "it will mean that documentation sucks," do you mean that the
documentation will rot faster if people are using the existing in-tree tests as their entrypoint?
Yes. And it will discourage to write documentation as well and read. Good documentation is like a good book. I like how doc.python.org works for me when I need something new to get about it, for example.
- What level of detailed comments? On the level of kunit-example-test.c?
- More concretely, then we'd have a comment block linking to the
Something like explaining each line with KUNIT / kunit in it. What it does and why it's written in the given form. Something like that.
example and then describing table driven unit testing?
- And then maybe another block about invariants instead of the
perhaps too-terse /* gcd(a,b) == gcd(b,a) */ ?
Right.
please update documentation to cover issues that you found and which motivated you to create these test cases.
Summarize this, please create usable documentation first.
Sounds good. I'm generally wary people not reading the docs, and of documentation examples becoming bitrotted faster than actual code. But so far KUnit seems to be doing relatively well on both fronts.
Dunno. As I told, I have created first unit test based on documentation (okay, I looked at the code, but you may read this as ratio was 90% doc / 10% existing code).
usage.rst is currently the best place for this, but it felt like it would quickly become a dumping ground for miscellaneous tips and tricks. I'll spend some time thinking if we want a new file or not, based on how much I want to write about the things this test demonstrated (EXPECT_*MSG, table driven tests, testing invariants, etc).
Thanks!
In offline discussions with David, the idea had come up with having a set of (relatively) simple tests in tree that the documentation could point to as examples of these things. That would keep the line count in usage.rst down a bit. (But then it would necessitate more tests like this math_test.c)