On Thu, Oct 22, 2020 at 12:04 PM Andy Shevchenko andriy.shevchenko@linux.intel.com wrote:
On Thu, Oct 22, 2020 at 11:53:50AM -0700, Brendan Higgins 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, please update documentation to cover issues that you found and which motivated you to create these test cases.
I don't entirely disagree; leaning too heavily on code examples can be detrimental to docs. That being said, when I use other people's code, I often don't even look at the docs. So, I think the ideal is to have both.
Why do we have docs in the first place? For test cases I think it's a crucial part, because tests many time are written by newbies, who would like to understand all under-the-hood stuff. You imply
Good point. Yeah, we don't really have any documentation that explains the internals at all. I agree: we need to fix that.
that they need to drop themselves into the code directly. It's very harsh to begin with Linux kernel development, really.
No, I was not trying to imply that everyone should just jump in the code and ignore the docs. I was just trying to point out that some people - myself included - rather see code than docs. Clearly some people prefer docs over code as well. Thus, I was trying to argue that both are appropriate.
Nevertheless, based on the other comments you sent, I don't think that's what we are talking about: sounds like you just want us to improve the docs first to make sure we do it. That's fine with me.
Summarize this, please create usable documentation first.
So, no go for this w/o documentation being up-to-date. Or be honest to everybody, it's sucks it needs to be removed. Then I will get your point.
-- With Best Regards, Andy Shevchenko