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@xxxxxxxxxxxxxxx> 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) -- With Best Regards, Andy Shevchenko
