diff mbox series

[v2] Documentation: kunit: rewrite writing first test instructions

Message ID 20220929132549.56452-1-bagasdotme@gmail.com
State New
Headers show
Series [v2] Documentation: kunit: rewrite writing first test instructions | expand

Commit Message

Bagas Sanjaya Sept. 29, 2022, 1:25 p.m. UTC
The wordings of step-by-step instructions on writing the first Kunit test
are instructing readers to write codes without knowing what these are about.
Rewrite these instructions to include the purpose of written code.

While at it, align the code blocks of these contents.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Changes since v1 [1]:

   - Fix jumped list numbering on writing the feature

 This patch is based on Khalid's full path to .kunitconfig patch [2].

 [1]: https://lore.kernel.org/linux-doc/20220929125458.52979-1-bagasdotme@gmail.com/
 [2]: https://lore.kernel.org/linux-doc/20220929085332.4155-1-khalid.masum.92@gmail.com/

 Documentation/dev-tools/kunit/start.rst | 40 ++++++++++++++-----------
 1 file changed, 22 insertions(+), 18 deletions(-)

Comments

David Gow Sept. 30, 2022, 6:42 a.m. UTC | #1
On Thu, Sep 29, 2022 at 9:26 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> The wordings of step-by-step instructions on writing the first Kunit test
> are instructing readers to write codes without knowing what these are about.
> Rewrite these instructions to include the purpose of written code.
>
> While at it, align the code blocks of these contents.
>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Changes since v1 [1]:
>
>    - Fix jumped list numbering on writing the feature
>
>  This patch is based on Khalid's full path to .kunitconfig patch [2].
>
>  [1]: https://lore.kernel.org/linux-doc/20220929125458.52979-1-bagasdotme@gmail.com/
>  [2]: https://lore.kernel.org/linux-doc/20220929085332.4155-1-khalid.masum.92@gmail.com/
>

While I like the idea behind this, the wording probably needs a bit of
tweaking. In addition, by describing everything in too much detail, I
fear we might just be adding some needless redundancy. My suspicion is
that everyone who's going to be writing KUnit tests already knows C
(or has access to better learning materials than this), so we're
unlikely to need to describe in detail that, e.g., misc_example_add()
adds two numbers together when the code is right there,

Also, I preferred v1 of the full path to .kunitconfig patch, so this
will need rebasing on top of whatever the final version of that turns
out to be.

In any case, further notes are inline, below.

Cheers,
-- David

>  Documentation/dev-tools/kunit/start.rst | 40 ++++++++++++++-----------
>  1 file changed, 22 insertions(+), 18 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index 7999874dc4ddb3..c0a5adf6d8d665 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -131,17 +131,19 @@ are built-in. Otherwise the module will need to be loaded.
>
>  Writing Your First Test
>  =======================
> -In your kernel repository, let's add some code that we can test.
> +In your kernel repository, let's add some code that we can test. For this
> +purpose, we are going to add simple addition driver.

A few issues here:
1. This should be "add _a_ simple addition driver".
2. That being said, I think we could simplify this further, and just
have "let's add a function to test, which adds two numbers together
and lives in its own driver.
3. This is an existing issue, but could we use "In _the_ kernel
repository" or "In _our_ kernel repository" to better match "let's"?

>
> -1. Create a file ``drivers/misc/example.h``, which includes:
> +1. Write the feature that will be tested. First, write the declaration
> +   for ``misc_example_add()`` in ``drivers/misc/example.h``:

As noted above, I think this is starting to verge on needless
redundancy here. I also think there was some benefit in pointing out
that this file is new, so needs to be created.

>
> -.. code-block:: c
> +   .. code-block:: c

Why are all of these code-block declarations being indented? It
doesn't seem to affect the actual documentation build, so I guess it's
harmless, but it'd be better not to have it change unnecessarily and
clutter up the diff.

>
>         int misc_example_add(int left, int right);
>
> -2. Create a file ``drivers/misc/example.c``, which includes:
> +   Then implement the function in ``drivers/misc/example.c``:

>
> -.. code-block:: c
> +   .. code-block:: c

Again, code-block indentation?

>
>         #include <linux/errno.h>
>
> @@ -152,24 +154,25 @@ In your kernel repository, let's add some code that we can test.
>                 return left + right;
>         }
>
> -3. Add the following lines to ``drivers/misc/Kconfig``:
> +2. Add Kconfig menu entry for the feature to ``drivers/misc/Kconfig``:

This needs rewording to add back an article ("a" or "the"), and we
probably want to call this a "Kconfig entry" rather than a "Kconfig
menu entry". Maybe "Add a Kconfig entry for the driver..."?

>
> -.. code-block:: kconfig
> +   .. code-block:: kconfig

Indentation again?

>
>         config MISC_EXAMPLE
>                 bool "My example"
>
> -4. Add the following lines to ``drivers/misc/Makefile``:
> +3. Add the kbuild goal that will build the feature to
> +   ``drivers/misc/Makefile``:

Kbuild goal? I've never heard of this being called a Kbuild goal before?

How about a "make target"?

>
> -.. code-block:: make
> +   .. code-block:: make

Indentation?

>
>         obj-$(CONFIG_MISC_EXAMPLE) += example.o
>
>  Now we are ready to write the test cases.
>
> -1. Add the below test case in ``drivers/misc/example_test.c``:
> +1. Write the test in ``drivers/misc/example_test.c``:

I really like this one!

>
> -.. code-block:: c
> +   .. code-block:: c

Indentation.

>
>         #include <kunit/test.h>
>         #include "example.h"
> @@ -202,31 +205,32 @@ Now we are ready to write the test cases.
>         };
>         kunit_test_suite(misc_example_test_suite);
>
> -2. Add the following lines to ``drivers/misc/Kconfig``:
> +2. Add following Kconfig entry for the test to ``drivers/misc/Kconfig``:

"Add _the_ following Kconfig entry".

>
> -.. code-block:: kconfig
> +   .. code-block:: kconfig

Indentation?

>
>         config MISC_EXAMPLE_TEST
>                 tristate "Test for my example" if !KUNIT_ALL_TESTS
>                 depends on MISC_EXAMPLE && KUNIT=y
>                 default KUNIT_ALL_TESTS
>
> -3. Add the following lines to ``drivers/misc/Makefile``:
> +3. Add kbuild goal of the test to ``drivers/misc/Makefile``:

Add a "make target" for the test?

>
> -.. code-block:: make
> +   .. code-block:: make

Indentation?

>
>         obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o
>
> -4. Add following configuration fragments to ``.kunit/.kunitconfig``:
> +4. Add following configuration fragments for the test to
> +   ``.kunit/.kunitconfig``:

"Add _the_ following".

I still slightly prefer "config entries" or similar here...

>
> -.. code-block:: none
> +   .. code-block:: none

Indentation?

>
>         CONFIG_MISC_EXAMPLE=y
>         CONFIG_MISC_EXAMPLE_TEST=y
>
>  5. Run the test:
>
> -.. code-block:: bash
> +   .. code-block:: bash

Indentation?

>
>         ./tools/testing/kunit/kunit.py run
>
> --
> An old man doll... just what I always wanted! - Clara
>
Bagas Sanjaya Sept. 30, 2022, 9:51 a.m. UTC | #2
On 9/30/22 13:42, David Gow wrote:
> 
> While I like the idea behind this, the wording probably needs a bit of
> tweaking. In addition, by describing everything in too much detail, I
> fear we might just be adding some needless redundancy. My suspicion is
> that everyone who's going to be writing KUnit tests already knows C
> (or has access to better learning materials than this), so we're
> unlikely to need to describe in detail that, e.g., misc_example_add()
> adds two numbers together when the code is right there,
> 

We should just say "First, write the driver implementation" (without
describing writing C code in detail), right?

>>
>> -.. code-block:: c
>> +   .. code-block:: c
> 
> Why are all of these code-block declarations being indented? It
> doesn't seem to affect the actual documentation build, so I guess it's
> harmless, but it'd be better not to have it change unnecessarily and
> clutter up the diff.
> 

The indentation for code-block directive is required, since the preceding
paragraph is multiline; otherwise there will be Sphinx warnings.

>>
>>         int misc_example_add(int left, int right);
>>
>> -2. Create a file ``drivers/misc/example.c``, which includes:
>> +   Then implement the function in ``drivers/misc/example.c``:
> 
>>
>> -.. code-block:: c
>> +   .. code-block:: c
> 
> Again, code-block indentation?

Yes, for consistency.

> 
>>
>>         #include <linux/errno.h>
>>
>> @@ -152,24 +154,25 @@ In your kernel repository, let's add some code that we can test.
>>                 return left + right;
>>         }
>>
>> -3. Add the following lines to ``drivers/misc/Kconfig``:
>> +2. Add Kconfig menu entry for the feature to ``drivers/misc/Kconfig``:
> 
> This needs rewording to add back an article ("a" or "the"), and we
> probably want to call this a "Kconfig entry" rather than a "Kconfig
> menu entry". Maybe "Add a Kconfig entry for the driver..."?
> 
>>
>> -.. code-block:: kconfig
>> +   .. code-block:: kconfig
> 
> Indentation again?

Yes, see above reply.

> 
>>
>>         config MISC_EXAMPLE
>>                 bool "My example"
>>
>> -4. Add the following lines to ``drivers/misc/Makefile``:
>> +3. Add the kbuild goal that will build the feature to
>> +   ``drivers/misc/Makefile``:
> 
> Kbuild goal? I've never heard of this being called a Kbuild goal before?
> 
> How about a "make target"?
> 

At the time of writing this patch, I use terminology in
Documentation/kbuild/makefiles.rst, which the "make target" is called
"Kbuild goal".

>>
>> -.. code-block:: make
>> +   .. code-block:: make
> 
> Indentation?

Yes, for consistency with the first code-block directive.

>>
>> -.. code-block:: c
>> +   .. code-block:: c
> 
> Indentation.
> 

See above reply.

>>
>> -.. code-block:: kconfig
>> +   .. code-block:: kconfig
> 
> Indentation?

See above reply.

>>
>> -.. code-block:: make
>> +   .. code-block:: make
> 
> Indentation?

See above reply.

>>
>> -.. code-block:: none
>> +   .. code-block:: none
> 
> Indentation?
> 

See above reply.

>>
>>         CONFIG_MISC_EXAMPLE=y
>>         CONFIG_MISC_EXAMPLE_TEST=y
>>
>>  5. Run the test:
>>
>> -.. code-block:: bash
>> +   .. code-block:: bash
> 
> Indentation?

See above reply.

Thanks for reviewing.
David Gow Sept. 30, 2022, 10:32 a.m. UTC | #3
On Fri, Sep 30, 2022 at 5:51 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On 9/30/22 13:42, David Gow wrote:
> >
> > While I like the idea behind this, the wording probably needs a bit of
> > tweaking. In addition, by describing everything in too much detail, I
> > fear we might just be adding some needless redundancy. My suspicion is
> > that everyone who's going to be writing KUnit tests already knows C
> > (or has access to better learning materials than this), so we're
> > unlikely to need to describe in detail that, e.g., misc_example_add()
> > adds two numbers together when the code is right there,
> >
>
> We should just say "First, write the driver implementation" (without
> describing writing C code in detail), right?
>

Yeah, that should be fine. I'm wavering back and forth on whether we
should call this a driver, given that in a lot of ways it isn't one,
but given it's in drivers/misc, it shouldn't be a problem.

> >>
> >> -.. code-block:: c
> >> +   .. code-block:: c
> >
> > Why are all of these code-block declarations being indented? It
> > doesn't seem to affect the actual documentation build, so I guess it's
> > harmless, but it'd be better not to have it change unnecessarily and
> > clutter up the diff.
> >
>
> The indentation for code-block directive is required, since the preceding
> paragraph is multiline; otherwise there will be Sphinx warnings.
>

I don't see any such warnings on my machine (which claims to have
sphinx-build 4.5.0).

Could you send an example warning, and your sphinx version to me so I
can try to reproduce it.

Regardless, if it's causing warnings, keep these changes. (Though it'd
be nice to include the warnings in the commit message, so it's obvious
that these are being re-aligned for a reason.)

> >>
> >>         int misc_example_add(int left, int right);
> >>
> >> -2. Create a file ``drivers/misc/example.c``, which includes:
> >> +   Then implement the function in ``drivers/misc/example.c``:
> >
> >>
> >> -.. code-block:: c
> >> +   .. code-block:: c
> >
> > Again, code-block indentation?
>
> Yes, for consistency.
>
> >
> >>
> >>         #include <linux/errno.h>
> >>
> >> @@ -152,24 +154,25 @@ In your kernel repository, let's add some code that we can test.
> >>                 return left + right;
> >>         }
> >>
> >> -3. Add the following lines to ``drivers/misc/Kconfig``:
> >> +2. Add Kconfig menu entry for the feature to ``drivers/misc/Kconfig``:
> >
> > This needs rewording to add back an article ("a" or "the"), and we
> > probably want to call this a "Kconfig entry" rather than a "Kconfig
> > menu entry". Maybe "Add a Kconfig entry for the driver..."?
> >
> >>
> >> -.. code-block:: kconfig
> >> +   .. code-block:: kconfig
> >
> > Indentation again?
>
> Yes, see above reply.
>
> >
> >>
> >>         config MISC_EXAMPLE
> >>                 bool "My example"
> >>
> >> -4. Add the following lines to ``drivers/misc/Makefile``:
> >> +3. Add the kbuild goal that will build the feature to
> >> +   ``drivers/misc/Makefile``:
> >
> > Kbuild goal? I've never heard of this being called a Kbuild goal before?
> >
> > How about a "make target"?
> >
>
> At the time of writing this patch, I use terminology in
> Documentation/kbuild/makefiles.rst, which the "make target" is called
> "Kbuild goal".
>
> >>
> >> -.. code-block:: make
> >> +   .. code-block:: make
> >
> > Indentation?
>
> Yes, for consistency with the first code-block directive.
>
> >>
> >> -.. code-block:: c
> >> +   .. code-block:: c
> >
> > Indentation.
> >
>
> See above reply.
>
> >>
> >> -.. code-block:: kconfig
> >> +   .. code-block:: kconfig
> >
> > Indentation?
>
> See above reply.
>
> >>
> >> -.. code-block:: make
> >> +   .. code-block:: make
> >
> > Indentation?
>
> See above reply.
>
> >>
> >> -.. code-block:: none
> >> +   .. code-block:: none
> >
> > Indentation?
> >
>
> See above reply.
>
> >>
> >>         CONFIG_MISC_EXAMPLE=y
> >>         CONFIG_MISC_EXAMPLE_TEST=y
> >>
> >>  5. Run the test:
> >>
> >> -.. code-block:: bash
> >> +   .. code-block:: bash
> >
> > Indentation?
>
> See above reply.
>
> Thanks for reviewing.
>
> --
> An old man doll... just what I always wanted! - Clara
>
> --
> You received this message because you are subscribed to the Google Groups "KUnit Development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to kunit-dev+unsubscribe@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/464981b6-d9d7-e656-261f-ef48661deaa2%40gmail.com.
Bagas Sanjaya Oct. 1, 2022, 3:07 a.m. UTC | #4
On 9/30/22 17:32, David Gow wrote:
>>
>> The indentation for code-block directive is required, since the preceding
>> paragraph is multiline; otherwise there will be Sphinx warnings.
>>
> 
> I don't see any such warnings on my machine (which claims to have
> sphinx-build 4.5.0).
> 
> Could you send an example warning, and your sphinx version to me so I
> can try to reproduce it.
> 
> Regardless, if it's causing warnings, keep these changes. (Though it'd
> be nice to include the warnings in the commit message, so it's obvious
> that these are being re-aligned for a reason.)
> 

I'm using Sphinx 2.4.4 (as installed from pip through
Documentation/sphinx/requirements.txt).

Sorry I can't reproduce the warning I mentioned earlier (I forget
the recipe that triggers it when writing the improv).

In any case, I'd like to keep code block aligning in the separate patch.
It would be nice to see code blocks aligned to the instructions list.
David Gow Oct. 1, 2022, 6:51 a.m. UTC | #5
On Sat, Oct 1, 2022 at 11:07 AM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On 9/30/22 17:32, David Gow wrote:
> >>
> >> The indentation for code-block directive is required, since the preceding
> >> paragraph is multiline; otherwise there will be Sphinx warnings.
> >>
> >
> > I don't see any such warnings on my machine (which claims to have
> > sphinx-build 4.5.0).
> >
> > Could you send an example warning, and your sphinx version to me so I
> > can try to reproduce it.
> >
> > Regardless, if it's causing warnings, keep these changes. (Though it'd
> > be nice to include the warnings in the commit message, so it's obvious
> > that these are being re-aligned for a reason.)
> >
>
> I'm using Sphinx 2.4.4 (as installed from pip through
> Documentation/sphinx/requirements.txt).
>
> Sorry I can't reproduce the warning I mentioned earlier (I forget
> the recipe that triggers it when writing the improv).
>
> In any case, I'd like to keep code block aligning in the separate patch.
> It would be nice to see code blocks aligned to the instructions list.
>

Sounds good. I tried to read through the reStructuredText spec to see
what it said about indentation here, and it was pretty vague, but if
it's causing warnings, we definitely should fix it. It would be nicer
(though not essential) to have it as a separate patch to the other
content changes.

Either way, feel free to send a new version (ideally based on top of
the kselftest/kunit tree, which has just had a number of patches
merged, including v1 of [1]).

Cheers,
-- David

[1]: https://lore.kernel.org/linux-doc/20220929085332.4155-1-khalid.masum.92@gmail.com/
Bagas Sanjaya Oct. 7, 2022, 3:03 a.m. UTC | #6
On 10/6/22 16:41, Sadiya Kazi wrote:
> Consider updating this section as below:
> In this section, you will learn how to write a program to test the addition
> of two numbers using KUnit. To do so, you must write the addition driver
> code followed by the test case.
> 
> 1.To write the addition driver code, follow the steps given below:
> 
>> a.Navigate to the Kernel repository.
> 
>     b.Create a file ``drivers/misc/example.h``.
>     c.In the ``example.h`` file, add the following code to declare the
> function ``misc_example_add()``:
> 
>>
>> -1. Create a file ``drivers/misc/example.h``, which includes:
>> +1. Write the feature that will be tested. First, write the declaration
>> +   for ``misc_example_add()`` in ``drivers/misc/example.h``:
>>
>> -.. code-block:: c
>> +   .. code-block:: c
>>
>>         int misc_example_add(int left, int right);
>>
>> -2. Create a file ``drivers/misc/example.c``, which includes:
>> +   Then implement the function in ``drivers/misc/example.c``:
> 
> 
> d. To implement the function, create a file ``drivers/misc/example.c` and
> add the following code to it:
> 
> 
>>
>> -.. code-block:: c
>> +   .. code-block:: c
>>
>>         #include <linux/errno.h>
>>
>> @@ -152,24 +154,25 @@ In your kernel repository, let's add some code that
>> we can test.
>>                 return left + right;
>>         }
>>
>> -3. Add the following lines to ``drivers/misc/Kconfig``:
>> +2. Add Kconfig menu entry for the feature to ``drivers/misc/Kconfig``:
>>
> 
> e. Update ``drivers/misc/Kconfig`` with the following code to add the
> driver configuration:
> 
> 
>>
>> -.. code-block:: kconfig
>> +   .. code-block:: kconfig
>>
>>         config MISC_EXAMPLE
>>                 bool "My example"
>>
>> -4. Add the following lines to ``drivers/misc/Makefile``:
>> +3. Add the kbuild goal that will build the feature to
>> +   ``drivers/misc/Makefile``:
>>
> f.To build the feature, update ``drivers/misc/Makefile`` with the following
> code:
> 
> 
>>
>> -.. code-block:: make
>> +   .. code-block:: make
>>
>>         obj-$(CONFIG_MISC_EXAMPLE) += example.o
>>
>>  Now we are ready to write the test cases.
>>
> 2. To write the test cases, follow the steps given below:
> 
>>
>> -1. Add the below test case in ``drivers/misc/example_test.c``:
>> +1. Write the test in ``drivers/misc/example_test.c``:
>>
>     a. Write the test in ``drivers/misc/example_test.c``:
> 
>>
>> -.. code-block:: c
>> +   .. code-block:: c
>>
>>         #include <kunit/test.h>
>>         #include "example.h"
>> @@ -202,31 +205,32 @@ Now we are ready to write the test cases.
>>         };
>>         kunit_test_suite(misc_example_test_suite);
>>
>> -2. Add the following lines to ``drivers/misc/Kconfig``:
>> +2. Add following Kconfig entry for the test to ``drivers/misc/Kconfig``:
>>
>     b. Add the following test configuration to ``drivers/misc/Kconfig``:
> 
>>
>> -.. code-block:: kconfig
>> +   .. code-block:: kconfig
>>
>>         config MISC_EXAMPLE_TEST
>>                 tristate "Test for my example" if !KUNIT_ALL_TESTS
>>                 depends on MISC_EXAMPLE && KUNIT=y
>>                 default KUNIT_ALL_TESTS
>>
>> -3. Add the following lines to ``drivers/misc/Makefile``:
>> +3. Add kbuild goal of the test to ``drivers/misc/Makefile``:
>>
>   c. Update ``drivers/misc/Makefile`` with the following code:
> 
>>
>> -.. code-block:: make
>> +   .. code-block:: make
>>
>>         obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o
>>
>> -4. Add following configuration fragments to ``.kunit/.kunitconfig``:
>> +4. Add following configuration fragments for the test to
>> +   ``.kunit/.kunitconfig``:
>>
> d. Add the following test configuration to ``.kunit/.kunitconfig``:
> 
>>
>> -.. code-block:: none
>> +   .. code-block:: none
>>
>>         CONFIG_MISC_EXAMPLE=y
>>         CONFIG_MISC_EXAMPLE_TEST=y
>>
>>  5. Run the test:
>>
> e. Run the test using the following command:
> 
>>
>> -.. code-block:: bash
>> +   .. code-block:: bash
>>
>>         ./tools/testing/kunit/kunit.py run
>>

I think the documentation assumes the knowledge of writing kernel
code (C language and build infrastructure). This means that the
instructions should be written for brevity.
diff mbox series

Patch

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index 7999874dc4ddb3..c0a5adf6d8d665 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -131,17 +131,19 @@  are built-in. Otherwise the module will need to be loaded.
 
 Writing Your First Test
 =======================
-In your kernel repository, let's add some code that we can test.
+In your kernel repository, let's add some code that we can test. For this
+purpose, we are going to add simple addition driver.
 
-1. Create a file ``drivers/misc/example.h``, which includes:
+1. Write the feature that will be tested. First, write the declaration
+   for ``misc_example_add()`` in ``drivers/misc/example.h``:
 
-.. code-block:: c
+   .. code-block:: c
 
 	int misc_example_add(int left, int right);
 
-2. Create a file ``drivers/misc/example.c``, which includes:
+   Then implement the function in ``drivers/misc/example.c``:
 
-.. code-block:: c
+   .. code-block:: c
 
 	#include <linux/errno.h>
 
@@ -152,24 +154,25 @@  In your kernel repository, let's add some code that we can test.
 		return left + right;
 	}
 
-3. Add the following lines to ``drivers/misc/Kconfig``:
+2. Add Kconfig menu entry for the feature to ``drivers/misc/Kconfig``:
 
-.. code-block:: kconfig
+   .. code-block:: kconfig
 
 	config MISC_EXAMPLE
 		bool "My example"
 
-4. Add the following lines to ``drivers/misc/Makefile``:
+3. Add the kbuild goal that will build the feature to
+   ``drivers/misc/Makefile``:
 
-.. code-block:: make
+   .. code-block:: make
 
 	obj-$(CONFIG_MISC_EXAMPLE) += example.o
 
 Now we are ready to write the test cases.
 
-1. Add the below test case in ``drivers/misc/example_test.c``:
+1. Write the test in ``drivers/misc/example_test.c``:
 
-.. code-block:: c
+   .. code-block:: c
 
 	#include <kunit/test.h>
 	#include "example.h"
@@ -202,31 +205,32 @@  Now we are ready to write the test cases.
 	};
 	kunit_test_suite(misc_example_test_suite);
 
-2. Add the following lines to ``drivers/misc/Kconfig``:
+2. Add following Kconfig entry for the test to ``drivers/misc/Kconfig``:
 
-.. code-block:: kconfig
+   .. code-block:: kconfig
 
 	config MISC_EXAMPLE_TEST
 		tristate "Test for my example" if !KUNIT_ALL_TESTS
 		depends on MISC_EXAMPLE && KUNIT=y
 		default KUNIT_ALL_TESTS
 
-3. Add the following lines to ``drivers/misc/Makefile``:
+3. Add kbuild goal of the test to ``drivers/misc/Makefile``:
 
-.. code-block:: make
+   .. code-block:: make
 
 	obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o
 
-4. Add following configuration fragments to ``.kunit/.kunitconfig``:
+4. Add following configuration fragments for the test to
+   ``.kunit/.kunitconfig``:
 
-.. code-block:: none
+   .. code-block:: none
 
 	CONFIG_MISC_EXAMPLE=y
 	CONFIG_MISC_EXAMPLE_TEST=y
 
 5. Run the test:
 
-.. code-block:: bash
+   .. code-block:: bash
 
 	./tools/testing/kunit/kunit.py run