Re: [PATCH v3] Documentation: test.h - fix warnings

[Brendan Higgins <brendanhiggins@google.com>]

On Thu, Apr 09, 2020 at 09:27:37PM +0000, Lothar Rubusch wrote:
> 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.
> 
> v2: Several documentation fixes
> 
> v3: Do not touch API documentation index
> 
> Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com>
> ---
>  Documentation/dev-tools/kunit/start.rst | 13 ++++++++-----
>  Documentation/dev-tools/kunit/usage.rst |  4 ++--
>  include/kunit/test.h                    |  7 ++++---
>  3 files changed, 14 insertions(+), 10 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..b8a8434443b0 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,13 @@ 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.

Err...we only have one param. I was fine with changing the name in the
kernel doc to `@...`, or something like `@suites_list...`, but I am not
okay with using both like this. I am posting a diff of what I am
thinking below.

>   *
>   * Registers @suites 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;
> -- 
> 2.20.1

diff --git a/include/kunit/test.h b/include/kunit/test.h
index 9b0c46a6ca1f..dce68c59ac76 100644
--- a/include/kunit/test.h
+++ b/include/kunit/test.h
@@ -232,9 +232,9 @@ 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
@@ -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);		\