memblock tests: update style of comments for memblock_reserve_*() functions

Update comments in memblock_reserve_*() functions to match the style used
in tests/alloc_*.c by rewording to make the expected outcome more apparent
and, if more than one memblock is involved, adding a visual of the
memory blocks.

If the comment has an extra column of spaces, remove the extra space at
the beginning of each line for consistency and to conform to Linux kernel
coding style.

Reviewed-by: David Hildenbrand <david@redhat.com>
Signed-off-by: Rebecca Mckeever <remckee0@gmail.com>
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>

tools/testing/memblock/tests/basic_api.c

@@ -303,12 +303,12 @@ static int memblock_add_checks(void)
 	return 0;
 }
 
- /*
+/*
-  * A simple test that marks a memory block of a specified base address
+ * A simple test that marks a memory block of a specified base address
-  * and size as reserved and to the collection of reserved memory regions
+ * and size as reserved and to the collection of reserved memory regions
-  * (memblock.reserved). It checks if a new entry was created and if region
+ * (memblock.reserved). Expect to create a new entry. The region counter
-  * counter and total memory size were correctly updated.
+ * and total memory size are updated.
-  */
+ */
 static int memblock_reserve_simple_check(void)
 {
 	struct memblock_region *rgn;
@@ -330,10 +330,15 @@ static int memblock_reserve_simple_check(void)
 }
 
 /*
- * A test that tries to mark two memory blocks that don't overlap as reserved
+ * A test that tries to mark two memory blocks that don't overlap as reserved:
- * and checks if two entries were correctly added to the collection of reserved
+ *
- * memory regions (memblock.reserved) and if this change was reflected in
+ *  |        +--+      +----------------+  |
- * memblock.reserved's total size and region counter.
+ *  |        |r1|      |       r2       |  |
+ *  +--------+--+------+----------------+--+
+ *
+ * Expect to add two entries to the collection of reserved memory regions
+ * (memblock.reserved). The total size and region counter for
+ * memblock.reserved are updated.
  */
 static int memblock_reserve_disjoint_check(void)
 {
@@ -368,13 +373,22 @@ static int memblock_reserve_disjoint_check(void)
 }
 
 /*
- * A test that tries to mark two memory blocks as reserved, where the
+ * A test that tries to mark two memory blocks r1 and r2 as reserved,
- * second one overlaps with the beginning of the first (that is
+ * where r2 overlaps with the beginning of r1 (that is
- * r1.base < r2.base + r2.size).
+ * r1.base < r2.base + r2.size):
- * It checks if two entries are merged into one region that starts at r2.base
+ *
- * and has size of two regions minus their intersection. The test also verifies
+ *  |  +--------------+--+--------------+  |
- * that memblock can still see only one entry and has a correct total size of
+ *  |  |       r2     |  |     r1       |  |
- * the reserved memory.
+ *  +--+--------------+--+--------------+--+
+ *     ^              ^
+ *     |              |
+ *     |              r1.base
+ *     |
+ *     r2.base
+ *
+ * Expect to merge two entries into one region that starts at r2.base and
+ * has size of two regions minus their intersection. The total size of the
+ * reserved memory is updated, and the region counter is not updated.
  */
 static int memblock_reserve_overlap_top_check(void)
 {
@@ -408,13 +422,22 @@ static int memblock_reserve_overlap_top_check(void)
 }
 
 /*
- * A test that tries to mark two memory blocks as reserved, where the
+ * A test that tries to mark two memory blocks r1 and r2 as reserved,
- * second one overlaps with the end of the first entry (that is
+ * where r2 overlaps with the end of r1 (that is
- * r2.base < r1.base + r1.size).
+ * r2.base < r1.base + r1.size):
- * It checks if two entries are merged into one region that starts at r1.base
+ *
- * and has size of two regions minus their intersection. It verifies that
+ *  |  +--------------+--+--------------+  |
- * memblock can still see only one entry and has a correct total size of the
+ *  |  |       r1     |  |     r2       |  |
- * reserved memory.
+ *  +--+--------------+--+--------------+--+
+ *     ^              ^
+ *     |              |
+ *     |              r2.base
+ *     |
+ *     r1.base
+ *
+ * Expect to merge two entries into one region that starts at r1.base and
+ * has size of two regions minus their intersection. The total size of the
+ * reserved memory is updated, and the region counter is not updated.
  */
 static int memblock_reserve_overlap_bottom_check(void)
 {
@@ -448,12 +471,21 @@ static int memblock_reserve_overlap_bottom_check(void)
 }
 
 /*
- * A test that tries to mark two memory blocks as reserved, where the second
+ * A test that tries to mark two memory blocks r1 and r2 as reserved,
- * one is within the range of the first entry (that is
+ * where r2 is within the range of r1 (that is
- * (r1.base < r2.base) && (r2.base + r2.size < r1.base + r1.size)).
+ * (r1.base < r2.base) && (r2.base + r2.size < r1.base + r1.size)):
- * It checks if two entries are merged into one region that stays the
+ *
- * same. The counter and total size of available memory are expected to not be
+ *  | +-----+--+---------------------------|
- * updated.
+ *  | |     |r2|          r1               |
+ *  +-+-----+--+---------------------------+
+ *    ^     ^
+ *    |     |
+ *    |     r2.base
+ *    |
+ *    r1.base
+ *
+ * Expect to merge two entries into one region that stays the same. The
+ * counter and total size of available memory are not updated.
  */
 static int memblock_reserve_within_check(void)
 {
@@ -485,7 +517,7 @@ static int memblock_reserve_within_check(void)
 
 /*
  * A simple test that tries to reserve the same memory block twice.
- * The region counter and total size of reserved memory are expected to not
+ * Expect the region counter and total size of reserved memory to not
  * be updated.
  */
 static int memblock_reserve_twice_check(void)