On Tue, Mar 15, 2022 at 10:44 PM Daniel Latypov dlatypov@google.com wrote:
Background: Currently, a reader looking at kunit/test.h will find the file is quite long, and the first meaty comment is a doc comment about struct kunit_resource.
Most users will not ever use the KUnit resource API directly. They'll use kunit_kmalloc() and friends, or decide it's simpler to do cleanups via labels (it often can be) instead of figuring out how to use the API.
It's also logically separate from everything else in test.h. Removing it from the file doesn't cause any compilation errors (since struct kunit has `struct list_head resources` to store them).
This commit: Let's move it into a kunit/resource.h file and give it a separate page in the docs, kunit/api/resource.rst.
We include resource.h at the bottom of test.h since
- don't want to force existing users to add a new include if they use the API
- it accesses `lock` inside `struct kunit` in a inline func
- so we can't just forward declare, and the alternatives require uninlining the func, adding hepers to lock/unlock, or other more invasive changes.
Now the first big comment in test.h is about kunit_case, which is a lot more relevant to what a new user wants to know.
A side effect of this is git blame won't properly track history by default, users need to run $ git blame -L ,1 -C17 include/kunit/resource.h
Signed-off-by: Daniel Latypov dlatypov@google.com
Aside from the discussion below,
Reviewed-by: Brendan Higgins brendanhiggins@google.com