Skip to contentSkip to conversation

Documentation: test.h - fix warnings

PATCH Superseded Lothar Rubusch 2 participants 7 messages Apr 8, 2020 – Apr 10, 2020

Subsystems (4)

v2 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 Documentation: test.h - fix warnings

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

- test.h: Fix some typos in kernel-doc parameter description.

- Documentation/*.rst: Fixing formatting issues, and a duplicate label issue, since using sphinx.ext.autosectionlabel in conf.py, referes to headers are generated automatically and sphinx will not complain about identical headers among documents anymore.

The downside is, automatically generated header labels within one document now cannot be overwritten manually anymore. Thus duplicate headers within one document have to have different wording, i.e. this patch modifies some headers.

- Documentation/api/*: Flipping over to a page "API" containing a single link to another page "API" seems like a formatting issue. The patch removes one level of indirection.

---
 Documentation/dev-tools/kunit/api/index.rst | 16 ----------------
 Documentation/dev-tools/kunit/index.rst     |  4 ++--
 Documentation/dev-tools/kunit/start.rst     | 13 ++++++++-----
 Documentation/dev-tools/kunit/usage.rst     |  4 ++--
 include/kunit/test.h                        |  5 +++--
 5 files changed, 15 insertions(+), 27 deletions(-)
 delete mode 100644 Documentation/dev-tools/kunit/api/index.rst
Documentation/dev-tools/kunit/api/index.rst deleted +0 -16
deleted file mode 100644
index 9b9bffe5d41a..000000000000
@@ -1,16 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-=============
-API Reference
-=============
-.. toctree::
-
-	test
-
-This section documents the KUnit kernel testing API. It is divided into the
-following sections:
-
-================================= ==============================================
-:doc:`test`                       documents all of the standard testing API
-                                  excluding mocking or mocking related features.
-================================= ==============================================
Documentation/dev-tools/kunit/index.rst +2 -2
index e93606ecfb01..640bba1f4896 100644
@@ -10,7 +10,7 @@ KUnit - Unit Testing for the Linux Kernel
 	start
 	usage
 	kunit-tool
-	api/index
+	api/test
 	faq
 
 What is KUnit?
@@ -88,6 +88,6 @@ How do I use it?
 
 *   :doc:`start` - for new users of KUnit
 *   :doc:`usage` - for a more detailed explanation of KUnit features
-*   :doc:`api/index` - for the list of KUnit APIs used for testing
+*   :doc:`api/test` - for the list of KUnit APIs used for testing
 *   :doc:`kunit-tool` - for more information on the kunit_tool helper script
 *   :doc:`faq` - for answers to some common questions about KUnit
Documentation/dev-tools/kunit/start.rst +8 -5
index e1c5ce80ce12..bb112cf70624 100644
@@ -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.
Documentation/dev-tools/kunit/usage.rst +2 -2
index 473a2361ec37..3c3fe8b5fecc 100644
@@ -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``).
include/kunit/test.h +3 -2
index 9b0c46a6ca1f..16d548b795b5 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,8 @@ 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.
+ * @...: a statically allocated list of &struct kunit_suite, assigned
+ *           to the pointer @suites.
  *
  * Registers @suites with the test framework. See &struct kunit_suite for
  * more information.
Signature · 1 line
2.20.1
Reviewed-by on v2 1/1
#1 lore raw
Quoted 16 lines · Lothar Rubusch

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

- test.h: Fix some typos in kernel-doc parameter description.

- Documentation/*.rst: Fixing formatting issues, and a duplicate label issue, since using sphinx.ext.autosectionlabel in conf.py, referes to headers are generated automatically and sphinx will not complain about identical headers among documents anymore.

The downside is, automatically generated header labels within one document now cannot be overwritten manually anymore. Thus duplicate headers within one document have to have different wording, i.e. this patch modifies some headers.

Quoted 5 lines

- Documentation/api/*: Flipping over to a page "API" containing a single link to another page "API" seems like a formatting issue. The patch removes one level of indirection.

A couple of minor comments, but other than that:

Thanks!

Quoted 21 lines
---
 Documentation/dev-tools/kunit/api/index.rst | 16 ----------------
 Documentation/dev-tools/kunit/index.rst     |  4 ++--
 Documentation/dev-tools/kunit/start.rst     | 13 ++++++++-----
 Documentation/dev-tools/kunit/usage.rst     |  4 ++--
 include/kunit/test.h                        |  5 +++--
 5 files changed, 15 insertions(+), 27 deletions(-)
 delete mode 100644 Documentation/dev-tools/kunit/api/index.rst
Documentation/dev-tools/kunit/api/index.rst deleted +0 -6
deleted file mode 100644
index 9b9bffe5d41a..000000000000
@@ -1,16 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-=============
-API Reference
-=============
-.. toctree::

Documentation/dev-tools/kunit/api/index.rst line 16

Quoted 10 lines
Documentation/dev-tools/kunit/api/index.rst deleted +0 -10
-
-       test
-
-This section documents the KUnit kernel testing API. It is divided into the
-following sections:
-
-================================= ==============================================
-:doc:`test`                       documents all of the standard testing API
-                                  excluding mocking or mocking related features.
-================================= ==============================================

Let's hold off on this. We have some other pages we would like to add to this directory soonish.

Quoted 100 lines
Documentation/dev-tools/kunit/index.rst +2 -2
index e93606ecfb01..640bba1f4896 100644
@@ -10,7 +10,7 @@ KUnit - Unit Testing for the Linux Kernel
        start
        usage
        kunit-tool
-       api/index
+       api/test
        faq
 
 What is KUnit?
@@ -88,6 +88,6 @@ How do I use it?
 
 *   :doc:`start` - for new users of KUnit
 *   :doc:`usage` - for a more detailed explanation of KUnit features
-*   :doc:`api/index` - for the list of KUnit APIs used for testing
+*   :doc:`api/test` - for the list of KUnit APIs used for testing
 *   :doc:`kunit-tool` - for more information on the kunit_tool helper script
 *   :doc:`faq` - for answers to some common questions about KUnit
Documentation/dev-tools/kunit/start.rst +8 -5
index e1c5ce80ce12..bb112cf70624 100644
@@ -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.
Documentation/dev-tools/kunit/usage.rst +2 -2
index 473a2361ec37..3c3fe8b5fecc 100644
@@ -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``).
include/kunit/test.h +1 -1
index 9b0c46a6ca1f..16d548b795b5 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 238

Quoted 8 lines
include/kunit/test.h +2 -1
@@ -232,7 +232,8 @@ 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.
+ * @...: a statically allocated list of &struct kunit_suite, assigned
+ *           to the pointer @suites.
  *
  * Registers @suites with the test framework. See &struct kunit_suite for

Can you change the @suites param here to match @...?

Thanks!

#2 lore raw
Quoted 56 lines · Brendan Higgins
Quoted 16 lines · Lothar Rubusch

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

- test.h: Fix some typos in kernel-doc parameter description.

- Documentation/*.rst: Fixing formatting issues, and a duplicate label issue, since using sphinx.ext.autosectionlabel in conf.py, referes to headers are generated automatically and sphinx will not complain about identical headers among documents anymore.

The downside is, automatically generated header labels within one document now cannot be overwritten manually anymore. Thus duplicate headers within one document have to have different wording, i.e. this patch modifies some headers.

Quoted 5 lines

- Documentation/api/*: Flipping over to a page "API" containing a single link to another page "API" seems like a formatting issue. The patch removes one level of indirection.

A couple of minor comments, but other than that:

Thanks!

Quoted 26 lines
---
 Documentation/dev-tools/kunit/api/index.rst | 16 ----------------
 Documentation/dev-tools/kunit/index.rst     |  4 ++--
 Documentation/dev-tools/kunit/start.rst     | 13 ++++++++-----
 Documentation/dev-tools/kunit/usage.rst     |  4 ++--
 include/kunit/test.h                        |  5 +++--
 5 files changed, 15 insertions(+), 27 deletions(-)
 delete mode 100644 Documentation/dev-tools/kunit/api/index.rst
Documentation/dev-tools/kunit/api/index.rst deleted +0 -11
deleted file mode 100644
index 9b9bffe5d41a..000000000000
@@ -1,16 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-=============
-API Reference
-=============
-.. toctree::
-
-       test
-
-This section documents the KUnit kernel testing API. It is divided into the
-following sections:
Quoted 8 lines

Documentation/dev-tools/kunit/api/index.rst line 16

Quoted 5 lines
Documentation/dev-tools/kunit/api/index.rst deleted +0 -5
-
-================================= ==============================================
-:doc:`test`                       documents all of the standard testing API
-                                  excluding mocking or mocking related features.
-================================= ==============================================

Let's hold off on this. We have some other pages we would like to add to this directory soonish.

Sure! I appologize, I just missed your last mail that you guys still plan something in the API section of the document.
So I leave the API page as is, no problem!

Quoted 94 lines
Quoted 94 lines
Documentation/dev-tools/kunit/index.rst +2 -2
index e93606ecfb01..640bba1f4896 100644
@@ -10,7 +10,7 @@ KUnit - Unit Testing for the Linux Kernel
        start
        usage
        kunit-tool
-       api/index
+       api/test
        faq
 
 What is KUnit?
@@ -88,6 +88,6 @@ How do I use it?
 
 *   :doc:`start` - for new users of KUnit
 *   :doc:`usage` - for a more detailed explanation of KUnit features
-*   :doc:`api/index` - for the list of KUnit APIs used for testing
+*   :doc:`api/test` - for the list of KUnit APIs used for testing
 *   :doc:`kunit-tool` - for more information on the kunit_tool helper script
 *   :doc:`faq` - for answers to some common questions about KUnit
Documentation/dev-tools/kunit/start.rst +8 -5
index e1c5ce80ce12..bb112cf70624 100644
@@ -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.
Documentation/dev-tools/kunit/usage.rst +2 -2
index 473a2361ec37..3c3fe8b5fecc 100644
@@ -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``).
include/kunit/test.h +0 -0
index 9b0c46a6ca1f..16d548b795b5 100644
@@ -175,7 +175,7 @@ struct kunit_suite {
        void (*exit)(struct kunit *test);
        struct kunit_case *test_cases;
 
Quoted 16 lines
Quoted 6 lines
include/kunit/test.h +1 -1
-       /* 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 238

Quoted 8 lines
include/kunit/test.h +2 -1
@@ -232,7 +232,8 @@ 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.
+ * @...: a statically allocated list of &struct kunit_suite, assigned
+ *           to the pointer @suites.
  *
  * Registers @suites with the test framework. See &struct kunit_suite for

Can you change the @suites param here to match @...?

You mean, in "Registers @suites with the test framework" to something rather like "Registers @... with"?
Hum, franckly I think, in the documentation it reads better having the name "suites", that's why I tried to
append a hint, that a passed list of struct kunit_suite initializes the pointer "suites". Then further in the doc
refered as suites, I think it becomes clear. But let me know. Shall I use @... instead?

Just give me a brief answer to this mail, then I adjust the patch and quickly resubmit.

Best,
L

#3 lore raw
Quoted 68 lines · Lothar Rubusch
Quoted 56 lines · Brendan Higgins
Quoted 16 lines · Lothar Rubusch

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

- test.h: Fix some typos in kernel-doc parameter description.

- Documentation/*.rst: Fixing formatting issues, and a duplicate label issue, since using sphinx.ext.autosectionlabel in conf.py, referes to headers are generated automatically and sphinx will not complain about identical headers among documents anymore.

The downside is, automatically generated header labels within one document now cannot be overwritten manually anymore. Thus duplicate headers within one document have to have different wording, i.e. this patch modifies some headers.

Quoted 5 lines

- Documentation/api/*: Flipping over to a page "API" containing a single link to another page "API" seems like a formatting issue. The patch removes one level of indirection.

A couple of minor comments, but other than that:

Thanks!

Quoted 26 lines
---
 Documentation/dev-tools/kunit/api/index.rst | 16 ----------------
 Documentation/dev-tools/kunit/index.rst     |  4 ++--
 Documentation/dev-tools/kunit/start.rst     | 13 ++++++++-----
 Documentation/dev-tools/kunit/usage.rst     |  4 ++--
 include/kunit/test.h                        |  5 +++--
 5 files changed, 15 insertions(+), 27 deletions(-)
 delete mode 100644 Documentation/dev-tools/kunit/api/index.rst
Documentation/dev-tools/kunit/api/index.rst deleted +0 -11
deleted file mode 100644
index 9b9bffe5d41a..000000000000
@@ -1,16 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-=============
-API Reference
-=============
-.. toctree::
-
-       test
-
-This section documents the KUnit kernel testing API. It is divided into the
-following sections:
Quoted 8 lines

Documentation/dev-tools/kunit/api/index.rst line 16

Quoted 5 lines
Documentation/dev-tools/kunit/api/index.rst deleted +0 -5
-
-================================= ==============================================
-:doc:`test`                       documents all of the standard testing API
-                                  excluding mocking or mocking related features.
-================================= ==============================================

Let's hold off on this. We have some other pages we would like to add to this directory soonish.

Quoted 3 lines

Sure! I appologize, I just missed your last mail that you guys still plan something in the API section of the document.
So I leave the API page as is, no problem!

No worries, we have let that go longer than I would like. So that's our fault, not yours :-)

Quoted 111 lines
Quoted 94 lines
Quoted 94 lines
Documentation/dev-tools/kunit/index.rst +2 -2
index e93606ecfb01..640bba1f4896 100644
@@ -10,7 +10,7 @@ KUnit - Unit Testing for the Linux Kernel
        start
        usage
        kunit-tool
-       api/index
+       api/test
        faq
 
 What is KUnit?
@@ -88,6 +88,6 @@ How do I use it?
 
 *   :doc:`start` - for new users of KUnit
 *   :doc:`usage` - for a more detailed explanation of KUnit features
-*   :doc:`api/index` - for the list of KUnit APIs used for testing
+*   :doc:`api/test` - for the list of KUnit APIs used for testing
 *   :doc:`kunit-tool` - for more information on the kunit_tool helper script
 *   :doc:`faq` - for answers to some common questions about KUnit
Documentation/dev-tools/kunit/start.rst +8 -5
index e1c5ce80ce12..bb112cf70624 100644
@@ -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.
Documentation/dev-tools/kunit/usage.rst +2 -2
index 473a2361ec37..3c3fe8b5fecc 100644
@@ -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``).
include/kunit/test.h +0 -0
index 9b0c46a6ca1f..16d548b795b5 100644
@@ -175,7 +175,7 @@ struct kunit_suite {
        void (*exit)(struct kunit *test);
        struct kunit_case *test_cases;
 
Quoted 16 lines
Quoted 6 lines
include/kunit/test.h +1 -1
-       /* 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 238

Quoted 8 lines
include/kunit/test.h +2 -1
@@ -232,7 +232,8 @@ 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.
+ * @...: a statically allocated list of &struct kunit_suite, assigned
+ *           to the pointer @suites.
  *
  * Registers @suites with the test framework. See &struct kunit_suite for

Can you change the @suites param here to match @...?

Quoted 8 lines

You mean, in "Registers @suites with the test framework" to something rather like "Registers @... with"?
Hum, franckly I think, in the documentation it reads better having the name "suites", that's why I tried to
append a hint, that a passed list of struct kunit_suite initializes the pointer "suites". Then further in the doc
refered as suites, I think it becomes clear. But let me know. Shall I use @... instead?

I agree that it doesn't read as well, but I like having the proper syntax highlighting and consistent naming over a mix and match.

Another alternative would be to replace ... with suites... and then @suites should work.

Either way is fine with me; it's a nasty macro anyway.

Quoted 2 lines

Just give me a brief answer to this mail, then I adjust the patch and quickly resubmit.

Thanks!

#4 lore raw
Quoted 197 lines · Brendan Higgins
Quoted 68 lines · Lothar Rubusch
Quoted 56 lines · Brendan Higgins
Quoted 16 lines · Lothar Rubusch

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

- test.h: Fix some typos in kernel-doc parameter description.

- Documentation/*.rst: Fixing formatting issues, and a duplicate label issue, since using sphinx.ext.autosectionlabel in conf.py, referes to headers are generated automatically and sphinx will not complain about identical headers among documents anymore.

The downside is, automatically generated header labels within one document now cannot be overwritten manually anymore. Thus duplicate headers within one document have to have different wording, i.e. this patch modifies some headers.

Quoted 5 lines

- Documentation/api/*: Flipping over to a page "API" containing a single link to another page "API" seems like a formatting issue. The patch removes one level of indirection.

A couple of minor comments, but other than that:

Thanks!

Quoted 26 lines
---
 Documentation/dev-tools/kunit/api/index.rst | 16 ----------------
 Documentation/dev-tools/kunit/index.rst     |  4 ++--
 Documentation/dev-tools/kunit/start.rst     | 13 ++++++++-----
 Documentation/dev-tools/kunit/usage.rst     |  4 ++--
 include/kunit/test.h                        |  5 +++--
 5 files changed, 15 insertions(+), 27 deletions(-)
 delete mode 100644 Documentation/dev-tools/kunit/api/index.rst
Documentation/dev-tools/kunit/api/index.rst deleted +0 -11
deleted file mode 100644
index 9b9bffe5d41a..000000000000
@@ -1,16 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-=============
-API Reference
-=============
-.. toctree::
-
-       test
-
-This section documents the KUnit kernel testing API. It is divided into the
-following sections:
Quoted 8 lines

Documentation/dev-tools/kunit/api/index.rst line 16

Quoted 5 lines
Documentation/dev-tools/kunit/api/index.rst deleted +0 -5
-
-================================= ==============================================
-:doc:`test`                       documents all of the standard testing API
-                                  excluding mocking or mocking related features.
-================================= ==============================================

Let's hold off on this. We have some other pages we would like to add to this directory soonish.

Quoted 3 lines

Sure! I appologize, I just missed your last mail that you guys still plan something in the API section of the document.
So I leave the API page as is, no problem!

No worries, we have let that go longer than I would like. So that's our fault, not yours :-)

Quoted 111 lines
Quoted 94 lines
Quoted 94 lines
Documentation/dev-tools/kunit/index.rst +2 -2
index e93606ecfb01..640bba1f4896 100644
@@ -10,7 +10,7 @@ KUnit - Unit Testing for the Linux Kernel
        start
        usage
        kunit-tool
-       api/index
+       api/test
        faq
 
 What is KUnit?
@@ -88,6 +88,6 @@ How do I use it?
 
 *   :doc:`start` - for new users of KUnit
 *   :doc:`usage` - for a more detailed explanation of KUnit features
-*   :doc:`api/index` - for the list of KUnit APIs used for testing
+*   :doc:`api/test` - for the list of KUnit APIs used for testing
 *   :doc:`kunit-tool` - for more information on the kunit_tool helper script
 *   :doc:`faq` - for answers to some common questions about KUnit
Documentation/dev-tools/kunit/start.rst +8 -5
index e1c5ce80ce12..bb112cf70624 100644
@@ -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.
Documentation/dev-tools/kunit/usage.rst +2 -2
index 473a2361ec37..3c3fe8b5fecc 100644
@@ -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``).
include/kunit/test.h +0 -0
index 9b0c46a6ca1f..16d548b795b5 100644
@@ -175,7 +175,7 @@ struct kunit_suite {
        void (*exit)(struct kunit *test);
        struct kunit_case *test_cases;
 
Quoted 16 lines
Quoted 6 lines
include/kunit/test.h +1 -1
-       /* 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 238

Quoted 8 lines
include/kunit/test.h +2 -1
@@ -232,7 +232,8 @@ 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.
+ * @...: a statically allocated list of &struct kunit_suite, assigned
+ *           to the pointer @suites.
  *
  * Registers @suites with the test framework. See &struct kunit_suite for

Can you change the @suites param here to match @...?

Quoted 8 lines

You mean, in "Registers @suites with the test framework" to something rather like "Registers @... with"?
Hum, franckly I think, in the documentation it reads better having the name "suites", that's why I tried to
append a hint, that a passed list of struct kunit_suite initializes the pointer "suites". Then further in the doc
refered as suites, I think it becomes clear. But let me know. Shall I use @... instead?

Quoted 2 lines

I agree that it doesn't read as well, but I like having the proper syntax highlighting and consistent naming over a mix and match.

I'll have another look on the syntax highlighting, leave out the api page removal and then resubmit. No problem. Thank you for all your patience!! I really appreciate if I can contribute to something!

Quoted 4 lines

Another alternative would be to replace ... with suites... and then @suites should work.

Either way is fine with me; it's a nasty macro anyway.

Yeah, that's what I read in the kernel-doc perl, too. Changing '...' to 'suites...'
is a code change, though. Possible, but IMHO would be a different patch. Actually, should we fix up the code for having a nicer documentation?!!

Somehow this feels like the next patches should go rather to sphinx/kernel-doc. Anyway, this patch is all about documentation.
A code change must be tested and verified and IMHO might be a different story.

Happy Easter!
L

#5 lore raw
Quoted 10 lines · Lothar Rubusch
Quoted 7 lines · Brendan Higgins
Quoted 5 lines · Lothar Rubusch
Quoted 2 lines · Brendan Higgins

On Wed, Apr 8, 2020 at 1:50 PM Lothar Rubusch <[email protected]> wrote:

[...]

Quoted 42 lines
Quoted 34 lines
Quoted 25 lines
Quoted 8 lines
Quoted 8 lines
include/kunit/test.h +0 -0
index 9b0c46a6ca1f..16d548b795b5 100644
@@ -175,7 +175,7 @@ struct kunit_suite {
        void (*exit)(struct kunit *test);
        struct kunit_case *test_cases;
 
Quoted 16 lines
Quoted 6 lines
include/kunit/test.h +1 -1
-       /* 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 238

Quoted 8 lines
include/kunit/test.h +2 -1
@@ -232,7 +232,8 @@ 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.
+ * @...: a statically allocated list of &struct kunit_suite, assigned
+ *           to the pointer @suites.
  *
  * Registers @suites with the test framework. See &struct kunit_suite for

Can you change the @suites param here to match @...?

Quoted 8 lines

You mean, in "Registers @suites with the test framework" to something rather like "Registers @... with"?
Hum, franckly I think, in the documentation it reads better having the name "suites", that's why I tried to
append a hint, that a passed list of struct kunit_suite initializes the pointer "suites". Then further in the doc
refered as suites, I think it becomes clear. But let me know. Shall I use @... instead?

Quoted 2 lines

I agree that it doesn't read as well, but I like having the proper syntax highlighting and consistent naming over a mix and match.

I'll have another look on the syntax highlighting, leave out the api page removal and then resubmit. No problem. Thank you for all your patience!! I really appreciate if I can contribute to something!

Quoted 8 lines
Quoted 4 lines

Another alternative would be to replace ... with suites... and then @suites should work.

Either way is fine with me; it's a nasty macro anyway.

Yeah, that's what I read in the kernel-doc perl, too. Changing '...' to 'suites...'
is a code change, though. Possible, but IMHO would be a different patch.

Good thought; that would usually be true most likely; however, in this case the documentation issue is in a comment in a code file, so no matter how you look at it, it is a code change. Also, it's such a minor change and since most of the KUnit code and documentation changes both go through the KUnit branch of the Kselftest tree anyway, so I think it's fine to just keep it all in one patch.

Quoted 1 line

Actually, should we fix up the code for having a nicer documentation?!!

Yes! Or at least I think so. Good documentation can be just as important, even more important than good code. I know there are plenty of developers that disagree with me on this point, but given what we are trying to do with KUnit, I say we are actually one of the places where our documentation is of utmost importance.

Still, great question to ask. Different kernel developers feel very differently about this point, and with good reason: some parts of the kernel will only really be used by people who can be expected to read all the relevant code, whereas other parts of the kernel may be used directly by a huge number of people most of which can't be expected to read all the code. It would make sense that these two groups of people would find different value in documentation.

Quoted 1 line

Somehow this feels like the next patches should go rather to sphinx/kernel-doc.

Not sure what you mean by this.

Quoted 2 lines

Anyway, this patch is all about documentation.
A code change must be tested and verified and IMHO might be a different story.

True, all code changes should be tested (I think all docs changes should be tested too :-) ), but testing this code here is really easy. You can test it with the following command:

./tools/testing/kunit/kunit.py run --timeout=60 --jobs=8 --defconfig

Quoted 2 lines

Happy Easter!

Happy Easter!

#6 lore raw
Quoted 66 lines · Brendan Higgins
Quoted 10 lines · Lothar Rubusch
Quoted 7 lines · Brendan Higgins
Quoted 5 lines · Lothar Rubusch
Quoted 2 lines · Brendan Higgins

On Wed, Apr 8, 2020 at 1:50 PM Lothar Rubusch <[email protected]> wrote:

[...]

Quoted 42 lines
Quoted 34 lines
Quoted 25 lines
Quoted 8 lines
Quoted 8 lines
include/kunit/test.h +0 -0
index 9b0c46a6ca1f..16d548b795b5 100644
@@ -175,7 +175,7 @@ struct kunit_suite {
        void (*exit)(struct kunit *test);
        struct kunit_case *test_cases;
 
Quoted 16 lines
Quoted 6 lines
include/kunit/test.h +1 -1
-       /* 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 238

Quoted 8 lines
include/kunit/test.h +2 -1
@@ -232,7 +232,8 @@ 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.
+ * @...: a statically allocated list of &struct kunit_suite, assigned
+ *           to the pointer @suites.
  *
  * Registers @suites with the test framework. See &struct kunit_suite for

Can you change the @suites param here to match @...?

Quoted 8 lines

You mean, in "Registers @suites with the test framework" to something rather like "Registers @... with"?
Hum, franckly I think, in the documentation it reads better having the name "suites", that's why I tried to
append a hint, that a passed list of struct kunit_suite initializes the pointer "suites". Then further in the doc
refered as suites, I think it becomes clear. But let me know. Shall I use @... instead?

Quoted 2 lines

I agree that it doesn't read as well, but I like having the proper syntax highlighting and consistent naming over a mix and match.

I'll have another look on the syntax highlighting, leave out the api page removal and then resubmit. No problem. Thank you for all your patience!! I really appreciate if I can contribute to something!

Quoted 8 lines
Quoted 4 lines

Another alternative would be to replace ... with suites... and then @suites should work.

Either way is fine with me; it's a nasty macro anyway.

Yeah, that's what I read in the kernel-doc perl, too. Changing '...' to 'suites...'
is a code change, though. Possible, but IMHO would be a different patch.

Quoted 6 lines

Good thought; that would usually be true most likely; however, in this case the documentation issue is in a comment in a code file, so no matter how you look at it, it is a code change. Also, it's such a minor change and since most of the KUnit code and documentation changes both go through the KUnit branch of the Kselftest tree anyway, so I think it's fine to just keep it all in one patch.

Absolutely Agree, this is cosmetics. Anyway, personally I'm also learning how to write to the community, i.e. I try to be careful. Thanks for the support!

Quoted 7 lines
Quoted 1 line

Actually, should we fix up the code for having a nicer documentation?!!

Yes! Or at least I think so. Good documentation can be just as important, even more important than good code. I know there are plenty of developers that disagree with me on this point, but given what we are trying to do with KUnit, I say we are actually one of the places where our documentation is of utmost importance.

Ah, this is actually not what I meant. I fully agree with you, good generated documentation is essential. I wanted to say, In a way I would prefer changing the scripts, rather than the sources to obtain better documentation. Practically it's easier to adjust the source directly.

Quoted 11 lines

Still, great question to ask. Different kernel developers feel very differently about this point, and with good reason: some parts of the kernel will only really be used by people who can be expected to read all the relevant code, whereas other parts of the kernel may be used directly by a huge number of people most of which can't be expected to read all the code. It would make sense that these two groups of people would find different value in documentation.

Quoted 1 line

Somehow this feels like the next patches should go rather to sphinx/kernel-doc.

Not sure what you mean by this.

Generally I see the limitation in the kernel-doc scripts not allowing for an anotation
for a better naming an unnamed variadics. I mean changing the source according to
the limitations of the scripts, is still kind of reasonable, low prio, low effort, easy...
Alternatively, extending the scripts may add more flexibility.
I saw worse things at the sphinx documentation e.g. duplicate label warnings when
using same headers inside the same document and sphinx.ext.autosection label active - which makes me feel like this should be rather patched, than rewritten in
the docs to fit that quirk of sphinx. Getting offtopic..

Quoted 8 lines
Quoted 2 lines

Anyway, this patch is all about documentation.
A code change must be tested and verified and IMHO might be a different story.

True, all code changes should be tested (I think all docs changes should be tested too :-) ), but testing this code here is really easy. You can test it with the following command:

./tools/testing/kunit/kunit.py run --timeout=60 --jobs=8 --defconfig

This is just awesome. Yesterday I was too lazy to still try anything. Thank you, I appreciate. I'll play around with that the next days.

Quoted 4 lines
Quoted 2 lines

Happy Easter!

Happy Easter! (again)

L