Skip to contentSkip to conversation

Documentation: test.h - fix warnings

PATCH In review Lothar Rubusch 2 participants 6 messages Apr 6, 2020 – Apr 8, 2020

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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
index 9b0c46a6ca1f..fe4ea388528b 100644
@@ -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
#1 lore raw
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 comment

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
index 9b0c46a6ca1f..fe4ea388528b 100644
@@ -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

#2 lore raw
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 comment

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
index 9b0c46a6ca1f..fe4ea388528b 100644
@@ -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

#3 lore raw
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 comment

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
index 9b0c46a6ca1f..fe4ea388528b 100644
@@ -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!

#4 lore raw

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

#5 lore raw
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