Documentation: test.h - fix warnings
PATCH 1/1 Documentation: test.h - fix warnings
Fix several sphinx warnings at 'make htmldocs'
- privately declared members not correctly declared as such
- 'suits' actually is not a function parameter, change declaration to fix warning but keep information in comment
--- include/kunit/test.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
include/kunit/test.h +2 -2
@@ -175,7 +175,7 @@ struct kunit_suite {void (*exit)(struct kunit *test);struct kunit_case *test_cases; -/* private - internal use only */ +/* private: internal use only. */ struct dentry *debugfs;char *log; };
@@ -232,7 +232,7 @@ void __kunit_test_suites_exit(struct kunit_suite **suites);* kunit_test_suites() - used to register one or more &struct kunit_suite * with KUnit. * -* @suites: a statically allocated list of &struct kunit_suite. +* suites - a statically allocated list of &struct kunit_suite. * * Registers @suites with the test framework. See &struct kunit_suite for * more information.
Signature · 1 line
2.20.1
Quoted 7 lines · Lothar Rubusch
Fix several sphinx warnings at 'make htmldocs'
- privately declared members not correctly declared as such
- 'suits' actually is not a function parameter, change declaration to fix warning but keep information in commentSigned-off-by Lothar Rubusch <[email protected]>
Thanks for taking care of this!
Quoted 18 lines
--- include/kunit/test.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)include/kunit/test.h +1
-1@@ -175,7 +175,7 @@ struct kunit_suite {void (*exit)(struct kunit *test);struct kunit_case *test_cases; -/* private - internal use only */ +/* private: internal use only. */ struct dentry *debugfs;char *log; };
include/kunit/test.h void __kunit_test_suites_exit(struct kunit_suite **suites); · line 235
Quoted 5 lines
include/kunit/test.h +1
-1@@ -232,7 +232,7 @@ void __kunit_test_suites_exit(struct kunit_suite **suites);* kunit_test_suites() - used to register one or more &struct kunit_suite * with KUnit. * -* @suites: a statically allocated list of &struct kunit_suite. +* suites - a statically allocated list of &struct kunit_suite.
So, I am pretty sure you can name the variadic arguments and then that gives you a valid parameter to use with kernel doc. Can you try that out?
include/kunit/test.h void __kunit_test_suites_exit(struct kunit_suite **suites); · line 237
Quoted 2 lines
include/kunit/test.h +0
-0* * Registers @suites with the test framework. See &struct kunit_suite for
Also, if my suggestion ends up not working, you should change this line to match.
Quoted 4 lines
include/kunit/test.h +0
-1* more information. --2.20.1
Quoted 24 lines · Brendan Higgins
Quoted 7 lines · Lothar Rubusch
Fix several sphinx warnings at 'make htmldocs'
- privately declared members not correctly declared as such
- 'suits' actually is not a function parameter, change declaration to fix warning but keep information in commentSigned-off-by Lothar Rubusch <[email protected]>Thanks for taking care of this!
Quoted 12 lines
--- include/kunit/test.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)include/kunit/test.h +0
-0@@ -175,7 +175,7 @@ struct kunit_suite {void (*exit)(struct kunit *test);struct kunit_case *test_cases;
Quoted 16 lines
include/kunit/test.h void __kunit_test_suites_exit(struct kunit_suite **suites); · line 235
Quoted 11 lines
include/kunit/test.h +2
-2-/* private - internal use only */ +/* private: internal use only. */ struct dentry *debugfs;char *log; };@@ -232,7 +232,7 @@ void __kunit_test_suites_exit(struct kunit_suite **suites);* kunit_test_suites() - used to register one or more &struct kunit_suite * with KUnit. * -* @suites: a statically allocated list of &struct kunit_suite. +* suites - a statically allocated list of &struct kunit_suite. So, I am pretty sure you can name the variadic arguments and then that gives you a valid parameter to use with kernel doc. Can you try that out?
You mean the warning "Excess function parameter 'suites' description in 'kunit_test_suites'"?
Honestly, due to the TODO in the same comment section, It seemed to me kind of a work-in-progress situation which I didn't dare to interfere.
Quoted 6 lines
include/kunit/test.h void __kunit_test_suites_exit(struct kunit_suite **suites); · line 237
Quoted 2 lines
include/kunit/test.h +0
-0* * Registers @suites with the test framework. See &struct kunit_suite for Also, if my suggestion ends up not working, you should change this line to match.
Sure, sounds interesting I can try to figure out. Thank you for the answer. L
Quoted 43 lines · Lothar Rubusch
Quoted 24 lines · Brendan Higgins
Quoted 7 lines · Lothar Rubusch
Fix several sphinx warnings at 'make htmldocs'
- privately declared members not correctly declared as such
- 'suits' actually is not a function parameter, change declaration to fix warning but keep information in commentSigned-off-by Lothar Rubusch <[email protected]>Thanks for taking care of this!
Quoted 12 lines
--- include/kunit/test.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)include/kunit/test.h +0
-0@@ -175,7 +175,7 @@ struct kunit_suite {void (*exit)(struct kunit *test);struct kunit_case *test_cases;Quoted 16 lines
include/kunit/test.h void __kunit_test_suites_exit(struct kunit_suite **suites); · line 235
Quoted 11 lines
include/kunit/test.h +2
-2-/* private - internal use only */ +/* private: internal use only. */ struct dentry *debugfs;char *log; };@@ -232,7 +232,7 @@ void __kunit_test_suites_exit(struct kunit_suite **suites);* kunit_test_suites() - used to register one or more &struct kunit_suite * with KUnit. * -* @suites: a statically allocated list of &struct kunit_suite. +* suites - a statically allocated list of &struct kunit_suite. So, I am pretty sure you can name the variadic arguments and then that gives you a valid parameter to use with kernel doc. Can you try that out?
Quoted 2 lines
You mean the warning "Excess function parameter 'suites' description in '
kunit_test_suites'"?
Yep, I just tried it out locally and it should work.
Quoted 2 lines
Honestly, due to the TODO in the same comment section, It seemed to me kind of a work-in-progress situation which I didn't dare to interfere.
Don't worry about that. Addressing that TODO is going to take some time.
Quoted 8 lines
Quoted 6 lines
include/kunit/test.h void __kunit_test_suites_exit(struct kunit_suite **suites); · line 237
Quoted 2 lines
include/kunit/test.h +0
-0* * Registers @suites with the test framework. See &struct kunit_suite for Also, if my suggestion ends up not working, you should change this line to match.
Sure, sounds interesting I can try to figure out. Thank you for the answer.
Thanks!
Hello,
(...)
Quoted 11 lines
Quoted 11 lines
Quoted 11 lines
include/kunit/test.h void __kunit_test_suites_exit(struct kunit_suite **suites); · line 235
Quoted 6 lines
include/kunit/test.h +1
-1@@ -232,7 +232,7 @@ void __kunit_test_suites_exit(struct kunit_suite **suites);* kunit_test_suites() - used to register one or more &struct kunit_suite * with KUnit. * -* @suites: a statically allocated list of &struct kunit_suite. +* suites - a statically allocated list of &struct kunit_suite. So, I am pretty sure you can name the variadic arguments and then that gives you a valid parameter to use with kernel doc. Can you try that out?
Quoted 4 lines
Quoted 2 lines
You mean the warning "Excess function parameter 'suites' description in '
kunit_test_suites'"?Yep, I just tried it out locally and it should work.
Something like '@...:' should be possible, to list the variadic under "Parameters", and display the corresponding description.
For curiosity I went through the kunit docs and fixed some formatting issues. Great piece of work, thanks for realizing kunit!
Last but not least, going through the document, there is a chapter "API" consisting of a single page with one link to "API". Is this on purpose? I would suggest to take out this level of indirection and remove the .rst file, linking API directly.
I'll send my proposals in a PATCH v2. Let me know then what you think after that.
Best,
L
Quoted 15 lines · Lothar Rubusch
Hello,
(...)
Quoted 11 lines
Quoted 11 lines
Quoted 11 lines
include/kunit/test.h void __kunit_test_suites_exit(struct kunit_suite **suites); · line 235
Quoted 6 lines
include/kunit/test.h +1
-1@@ -232,7 +232,7 @@ void __kunit_test_suites_exit(struct kunit_suite **suites);* kunit_test_suites() - used to register one or more &struct kunit_suite * with KUnit. * -* @suites: a statically allocated list of &struct kunit_suite. +* suites - a statically allocated list of &struct kunit_suite. So, I am pretty sure you can name the variadic arguments and then that gives you a valid parameter to use with kernel doc. Can you try that out?
Quoted 7 lines
Quoted 4 lines
Quoted 2 lines
You mean the warning "Excess function parameter 'suites' description in '
kunit_test_suites'"?Yep, I just tried it out locally and it should work.
Something like '@...:' should be possible, to list the variadic under "Parameters", and display the corresponding description.
That'll probably work, or you can change the ... to something like suites_param... and change the corresponding __VA_ARGS__ to suites_param. Either way works for me.
Quoted 2 lines
For curiosity I went through the kunit docs and fixed some formatting issues. Great piece of work, thanks for realizing kunit!
Thanks!
Quoted 4 lines
Last but not least, going through the document, there is a chapter "API" consisting of a single page with one link to "API". Is this on purpose? I would suggest to take out this level of indirection and remove the .rst file, linking API directly.
Yeah, it's because we have some other features that we are planning on adding soonish which will have their own pages.
Quoted 2 lines
I'll send my proposals in a PATCH v2. Let me know then what you think after that.
Looking forward to them!
Cheers