Linux-kselftest Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH v5] Documentation: test.h - fix warnings
@ 2020-04-15 20:16 Lothar Rubusch
  2020-04-20 16:49 ` Brendan Higgins
  2020-04-21 19:33 ` Jonathan Corbet
  0 siblings, 2 replies; 4+ messages in thread
From: Lothar Rubusch @ 2020-04-15 20:16 UTC (permalink / raw)
  To: brendanhiggins, corbet; +Cc: kunit-dev, linux-kselftest, Lothar Rubusch

Fix warnings at 'make htmldocs', and formatting issues in the resulting
documentation.

- test.h: Fix annotation in kernel-doc parameter description.

- Documentation/*.rst: Fixing formatting issues, and a duplicate label
  issue due to usage of sphinx.ext.autosectionlabel and identical labels
  within one document (sphinx warning)

Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com>
---
v2: Several documentation fixes

v3: Do not touch API documentation index

v4: Replace macro argument in test.h by named variadic argument

v5: Patch format fixed

NB: checkpatch.pl will complain about flow control statements (i.e. usage
    of "return") within the macro kunit_test_suites(suites_list...).

Better? I feel I'm making you a lot of extra work. I'm really sorry for
all this fuzz!

 Documentation/dev-tools/kunit/start.rst | 13 ++++++++-----
 Documentation/dev-tools/kunit/usage.rst |  4 ++--
 include/kunit/test.h                    | 12 ++++++------
 3 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index e1c5ce80ce12..bb112cf70624 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -32,15 +32,17 @@ test targets as well. The ``.kunitconfig`` should also contain any other config
 options required by the tests.
 
 A good starting point for a ``.kunitconfig`` is the KUnit defconfig:
+
 .. code-block:: bash
 
 	cd $PATH_TO_LINUX_REPO
 	cp arch/um/configs/kunit_defconfig .kunitconfig
 
 You can then add any other Kconfig options you wish, e.g.:
+
 .. code-block:: none
 
-        CONFIG_LIST_KUNIT_TEST=y
+	CONFIG_LIST_KUNIT_TEST=y
 
 :doc:`kunit_tool <kunit-tool>` will ensure that all config options set in
 ``.kunitconfig`` are set in the kernel ``.config`` before running the tests.
@@ -54,8 +56,8 @@ using.
    other tools (such as make menuconfig) to adjust other config options.
 
 
-Running the tests
------------------
+Running the tests (KUnit Wrapper)
+---------------------------------
 
 To make sure that everything is set up correctly, simply invoke the Python
 wrapper from your kernel repo:
@@ -105,8 +107,9 @@ have config options ending in ``_KUNIT_TEST``.
 KUnit and KUnit tests can be compiled as modules: in this case the tests in a
 module will be run when the module is loaded.
 
-Running the tests
------------------
+
+Running the tests (w/o KUnit Wrapper)
+-------------------------------------
 
 Build and run your kernel as usual. Test output will be written to the kernel
 log in `TAP <https://testanything.org/>`_ format.
diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst
index 473a2361ec37..3c3fe8b5fecc 100644
--- a/Documentation/dev-tools/kunit/usage.rst
+++ b/Documentation/dev-tools/kunit/usage.rst
@@ -595,7 +595,7 @@ able to run one test case per invocation.
 KUnit debugfs representation
 ============================
 When kunit test suites are initialized, they create an associated directory
-in /sys/kernel/debug/kunit/<test-suite>.  The directory contains one file
+in ``/sys/kernel/debug/kunit/<test-suite>``.  The directory contains one file
 
 - results: "cat results" displays results of each test case and the results
   of the entire suite for the last test run.
@@ -604,4 +604,4 @@ The debugfs representation is primarily of use when kunit test suites are
 run in a native environment, either as modules or builtin.  Having a way
 to display results like this is valuable as otherwise results can be
 intermixed with other events in dmesg output.  The maximum size of each
-results file is KUNIT_LOG_SIZE bytes (defined in include/kunit/test.h).
+results file is KUNIT_LOG_SIZE bytes (defined in ``include/kunit/test.h``).
diff --git a/include/kunit/test.h b/include/kunit/test.h
index 9b0c46a6ca1f..47e61e1d5337 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,12 +232,12 @@ 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_list...: a statically allocated list of &struct kunit_suite.
  *
- * Registers @suites with the test framework. See &struct kunit_suite for
+ * Registers @suites_list with the test framework. See &struct kunit_suite for
  * more information.
  *
- * When builtin,  KUnit tests are all run as late_initcalls; this means
+ * When builtin, KUnit tests are all run as late_initcalls; this means
  * that they cannot test anything where tests must run at a different init
  * phase. One significant restriction resulting from this is that KUnit
  * cannot reliably test anything that is initialize in the late_init phase;
@@ -253,8 +253,8 @@ void __kunit_test_suites_exit(struct kunit_suite **suites);
  * tests from the same place, and at the very least to do so after
  * everything else is definitely initialized.
  */
-#define kunit_test_suites(...)						\
-	static struct kunit_suite *suites[] = { __VA_ARGS__, NULL};	\
+#define kunit_test_suites(suites_list...)				\
+	static struct kunit_suite *suites[] = {suites_list, NULL};	\
 	static int kunit_test_suites_init(void)				\
 	{								\
 		return __kunit_test_suites_init(suites);		\
-- 
2.20.1


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH v5] Documentation: test.h - fix warnings
  2020-04-15 20:16 [PATCH v5] Documentation: test.h - fix warnings Lothar Rubusch
@ 2020-04-20 16:49 ` Brendan Higgins
  2020-04-21 19:33 ` Jonathan Corbet
  1 sibling, 0 replies; 4+ messages in thread
From: Brendan Higgins @ 2020-04-20 16:49 UTC (permalink / raw)
  To: Lothar Rubusch
  Cc: Jonathan Corbet, KUnit Development, open list:KERNEL SELFTEST FRAMEWORK

On Wed, Apr 15, 2020 at 1:18 PM Lothar Rubusch <l.rubusch@gmail.com> wrote:
>
> Fix warnings at 'make htmldocs', and formatting issues in the resulting
> documentation.
>
> - test.h: Fix annotation in kernel-doc parameter description.
>
> - Documentation/*.rst: Fixing formatting issues, and a duplicate label
>   issue due to usage of sphinx.ext.autosectionlabel and identical labels
>   within one document (sphinx warning)
>
> Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com>

Reviewed-by: Brendan Higgins <brendanhiggins@google.com>

FYI: I already gave you a Reviewed-by. In the future, please add
Reviewed-bys you get to any follow-up patches. (You don't have to do
anything if you get a Reviewed-by and don't have to send follow-up
revisions.)

Let me know if you have any questions about how this works.

> ---
> v2: Several documentation fixes
>
> v3: Do not touch API documentation index
>
> v4: Replace macro argument in test.h by named variadic argument
>
> v5: Patch format fixed
>
> NB: checkpatch.pl will complain about flow control statements (i.e. usage
>     of "return") within the macro kunit_test_suites(suites_list...).

Yeah, it's a "bad code smell", but not necessarily always wrong, so
right now we don't have anything better than to just always warn and
sometimes ignore.

> Better?

Looks good to me!

> I feel I'm making you a lot of extra work. I'm really sorry for
> all this fuzz!

No worries. Our documentation/on-boarding processes are at best not
very good and at worst non-existent, so this is pretty much just par
for the course.

Thanks for sticking with this! I know getting up to speed on upstream
Linux kernel development can be painful and tedious. I have been there
myself, and I still make lots of silly mistakes. :-)

Sorry, if I ever seemed impatient: I am not annoyed. I respond to
dozens of emails everyday, so I can sometimes get rather terse as a
result of trying to be expedient. I hope you understand!

Trust me, once you go to a Linux conference and you meet some devs,
you will find that in person, most of us are super nice people, even
the ones who can *seem* mean and frustrated on the list.

Thanks for the patch! Hope to see you around in the community!

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH v5] Documentation: test.h - fix warnings
  2020-04-15 20:16 [PATCH v5] Documentation: test.h - fix warnings Lothar Rubusch
  2020-04-20 16:49 ` Brendan Higgins
@ 2020-04-21 19:33 ` Jonathan Corbet
  2020-05-22 22:24   ` shuah
  1 sibling, 1 reply; 4+ messages in thread
From: Jonathan Corbet @ 2020-04-21 19:33 UTC (permalink / raw)
  To: Lothar Rubusch; +Cc: brendanhiggins, kunit-dev, linux-kselftest

On Wed, 15 Apr 2020 20:16:53 +0000
Lothar Rubusch <l.rubusch@gmail.com> wrote:

> Fix warnings at 'make htmldocs', and formatting issues in the resulting
> documentation.
> 
> - test.h: Fix annotation in kernel-doc parameter description.
> 
> - Documentation/*.rst: Fixing formatting issues, and a duplicate label
>   issue due to usage of sphinx.ext.autosectionlabel and identical labels
>   within one document (sphinx warning)
> 
> Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com>
> ---
> v2: Several documentation fixes
> 
> v3: Do not touch API documentation index
> 
> v4: Replace macro argument in test.h by named variadic argument
> 
> v5: Patch format fixed
> 
> NB: checkpatch.pl will complain about flow control statements (i.e. usage
>     of "return") within the macro kunit_test_suites(suites_list...).
> 
> Better? I feel I'm making you a lot of extra work. I'm really sorry for
> all this fuzz!

So I'm assuming this will go via Shuah's tree; let me know if that's
incorrect.

Thanks,

jon

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH v5] Documentation: test.h - fix warnings
  2020-04-21 19:33 ` Jonathan Corbet
@ 2020-05-22 22:24   ` shuah
  0 siblings, 0 replies; 4+ messages in thread
From: shuah @ 2020-05-22 22:24 UTC (permalink / raw)
  To: Jonathan Corbet, Lothar Rubusch
  Cc: brendanhiggins, kunit-dev, linux-kselftest, shuah

On 4/21/20 1:33 PM, Jonathan Corbet wrote:
> On Wed, 15 Apr 2020 20:16:53 +0000
> Lothar Rubusch <l.rubusch@gmail.com> wrote:
> 
>> Fix warnings at 'make htmldocs', and formatting issues in the resulting
>> documentation.
>>
>> - test.h: Fix annotation in kernel-doc parameter description.
>>
>> - Documentation/*.rst: Fixing formatting issues, and a duplicate label
>>    issue due to usage of sphinx.ext.autosectionlabel and identical labels
>>    within one document (sphinx warning)
>>
>> Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com>
>> ---
>> v2: Several documentation fixes
>>
>> v3: Do not touch API documentation index
>>
>> v4: Replace macro argument in test.h by named variadic argument
>>
>> v5: Patch format fixed
>>
>> NB: checkpatch.pl will complain about flow control statements (i.e. usage
>>      of "return") within the macro kunit_test_suites(suites_list...).
>>
>> Better? I feel I'm making you a lot of extra work. I'm really sorry for
>> all this fuzz!
> 
> So I'm assuming this will go via Shuah's tree; let me know if that's
> incorrect.
> 

Applied to linux-kselftest kunit for Linux 5.8-rc1.

thanks,
-- Shuah

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, back to index

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-04-15 20:16 [PATCH v5] Documentation: test.h - fix warnings Lothar Rubusch
2020-04-20 16:49 ` Brendan Higgins
2020-04-21 19:33 ` Jonathan Corbet
2020-05-22 22:24   ` shuah

Linux-kselftest Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-kselftest/0 linux-kselftest/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-kselftest linux-kselftest/ https://lore.kernel.org/linux-kselftest \
		linux-kselftest@vger.kernel.org
	public-inbox-index linux-kselftest

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-kselftest


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git