| Message ID | 20200406214130.21224-1-l.rubusch@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Documentation: test.h - fix warnings | expand |
On Mon, Apr 6, 2020 at 2:41 PM Lothar Rubusch <l.rubusch@gmail.com> wrote: > > 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 > > Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com> Thanks for taking care of this! > --- > include/kunit/test.h | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git a/include/kunit/test.h b/include/kunit/test.h > index 9b0c46a6ca1f..fe4ea388528b 100644 > --- a/include/kunit/test.h > +++ b/include/kunit/test.h > @@ -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. 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? > * > * 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. > * more information. > -- > 2.20.1 >
On Tue, Apr 7, 2020 at 10:49 PM Brendan Higgins <brendanhiggins@google.com> wrote: > > On Mon, Apr 6, 2020 at 2:41 PM Lothar Rubusch <l.rubusch@gmail.com> wrote: > > > > 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 > > > > Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com> > > Thanks for taking care of this! > > > --- > > include/kunit/test.h | 4 ++-- > > 1 file changed, 2 insertions(+), 2 deletions(-) > > > > diff --git a/include/kunit/test.h b/include/kunit/test.h > > index 9b0c46a6ca1f..fe4ea388528b 100644 > > --- a/include/kunit/test.h > > +++ b/include/kunit/test.h > > @@ -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. > > 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. > > * > > * 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
On Tue, Apr 7, 2020 at 3:30 PM Lothar Rubusch <l.rubusch@gmail.com> wrote: > > On Tue, Apr 7, 2020 at 10:49 PM Brendan Higgins > <brendanhiggins@google.com> wrote: > > > > On Mon, Apr 6, 2020 at 2:41 PM Lothar Rubusch <l.rubusch@gmail.com> wrote: > > > > > > 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 > > > > > > Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com> > > > > Thanks for taking care of this! > > > > > --- > > > include/kunit/test.h | 4 ++-- > > > 1 file changed, 2 insertions(+), 2 deletions(-) > > > > > > diff --git a/include/kunit/test.h b/include/kunit/test.h > > > index 9b0c46a6ca1f..fe4ea388528b 100644 > > > --- a/include/kunit/test.h > > > +++ b/include/kunit/test.h > > > @@ -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. > > > > 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'"? Yep, I just tried it out locally and it should work. > 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. > > > * > > > * 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, (...) > > > > @@ -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'"? > > 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
On Wed, Apr 8, 2020 at 1:39 PM Lothar Rubusch <l.rubusch@gmail.com> wrote: > > Hello, > > (...) > > > > > @@ -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'"? > > > > 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. > For curiosity I went through the kunit docs and fixed some formatting > issues. Great piece of work, thanks for realizing kunit! Thanks! > 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. > I'll send my proposals in a PATCH v2. Let me know then what you think > after that. Looking forward to them! Cheers
diff --git a/include/kunit/test.h b/include/kunit/test.h index 9b0c46a6ca1f..fe4ea388528b 100644 --- a/include/kunit/test.h +++ b/include/kunit/test.h @@ -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.
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 Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com> --- include/kunit/test.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)