[v2] lib/bitmap: Fix bitmap_scatter() and bitmap_gather() kernel doc

[PATCH v2] lib/bitmap: Fix bitmap_scatter() and bitmap_gather() kernel doc

Posted by Herve Codina 1 year, 11 months ago

The make htmldoc command failed with the following error
  ... include/linux/bitmap.h:524: ERROR: Unexpected indentation.
  ... include/linux/bitmap.h:524: CRITICAL: Unexpected section title or transition.

Move the visual representation to a literal block.

Fixes: de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-kernel/20240312153059.3ffde1b7@canb.auug.org.au/
Signed-off-by: Herve Codina <herve.codina@bootlin.com>
---

Changes v1 -> v2
  Add Fixes, Reported-by and Closes tags

 include/linux/bitmap.h | 44 ++++++++++++++++++++++--------------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/include/linux/bitmap.h b/include/linux/bitmap.h
index fb3a9c93ac86..aa4096126553 100644
--- a/include/linux/bitmap.h
+++ b/include/linux/bitmap.h
@@ -522,17 +522,18 @@ static inline void bitmap_replace(unsigned long *dst,
  *
  * (Bits 0, 1, 2, 3, 4, 5 are copied to the bits 0, 1, 4, 8, 9, 12)
  *
- * A more 'visual' description of the operation:
- * src:  0000000001011010
- *                 ||||||
- *          +------+|||||
- *          |  +----+||||
- *          |  |+----+|||
- *          |  ||   +-+||
- *          |  ||   |  ||
- * mask: ...v..vv...v..vv
- *       ...0..11...0..10
- * dst:  0000001100000010
+ * A more 'visual' description of the operation::
+ *
+ *	src:  0000000001011010
+ *	                ||||||
+ *	         +------+|||||
+ *	         |  +----+||||
+ *	         |  |+----+|||
+ *	         |  ||   +-+||
+ *	         |  ||   |  ||
+ *	mask: ...v..vv...v..vv
+ *	      ...0..11...0..10
+ *	dst:  0000001100000010
  *
  * A relationship exists between bitmap_scatter() and bitmap_gather().
  * bitmap_gather() can be seen as the 'reverse' bitmap_scatter() operation.
@@ -568,16 +569,17 @@ static inline void bitmap_scatter(unsigned long *dst, const unsigned long *src,
  *
  * (Bits 0, 1, 4, 8, 9, 12 are copied to the bits 0, 1, 2, 3, 4, 5)
  *
- * A more 'visual' description of the operation:
- * mask: ...v..vv...v..vv
- * src:  0000001100000010
- *          ^  ^^   ^   0
- *          |  ||   |  10
- *          |  ||   > 010
- *          |  |+--> 1010
- *          |  +--> 11010
- *          +----> 011010
- * dst:  0000000000011010
+ * A more 'visual' description of the operation::
+ *
+ *	mask: ...v..vv...v..vv
+ *	src:  0000001100000010
+ *	         ^  ^^   ^   0
+ *	         |  ||   |  10
+ *	         |  ||   > 010
+ *	         |  |+--> 1010
+ *	         |  +--> 11010
+ *	         +----> 011010
+ *	dst:  0000000000011010
  *
  * A relationship exists between bitmap_gather() and bitmap_scatter(). See
  * bitmap_scatter() for the bitmap scatter detailed operations.
-- 
2.44.0

Re: [PATCH v2] lib/bitmap: Fix bitmap_scatter() and bitmap_gather() kernel doc

Posted by Jakub Kicinski 1 year, 10 months ago

On Thu, 14 Mar 2024 13:00:06 +0100 Herve Codina wrote:
> The make htmldoc command failed with the following error
>   ... include/linux/bitmap.h:524: ERROR: Unexpected indentation.
>   ... include/linux/bitmap.h:524: CRITICAL: Unexpected section title or transition.
> 
> Move the visual representation to a literal block.
> 
> Fixes: de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Closes: https://lore.kernel.org/linux-kernel/20240312153059.3ffde1b7@canb.auug.org.au/
> Signed-off-by: Herve Codina <herve.codina@bootlin.com>

We took the offending commit via netdev, so I feel responsible. Please
LMK if anyone else is planning to apply this fix, otherwise we'll take
it and ship it to Linus on Thursday (19th).

Re: [PATCH v2] lib/bitmap: Fix bitmap_scatter() and bitmap_gather() kernel doc

Posted by Yury Norov 1 year, 10 months ago

On Tue, Mar 19, 2024 at 07:33:38PM -0700, Jakub Kicinski wrote:
> On Thu, 14 Mar 2024 13:00:06 +0100 Herve Codina wrote:
> > The make htmldoc command failed with the following error
> >   ... include/linux/bitmap.h:524: ERROR: Unexpected indentation.
> >   ... include/linux/bitmap.h:524: CRITICAL: Unexpected section title or transition.
> > 
> > Move the visual representation to a literal block.
> > 
> > Fixes: de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
> > Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> > Closes: https://lore.kernel.org/linux-kernel/20240312153059.3ffde1b7@canb.auug.org.au/
> > Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> 
> We took the offending commit via netdev, so I feel responsible. Please
> LMK if anyone else is planning to apply this fix, otherwise we'll take
> it and ship it to Linus on Thursday (19th).

Please go ahead and add my

Acked-by: Yury Norov <yury.norov@gmail.com>

Re: [PATCH v2] lib/bitmap: Fix bitmap_scatter() and bitmap_gather() kernel doc

Posted by Jakub Kicinski 1 year, 10 months ago

On Wed, 20 Mar 2024 11:34:40 -0700 Yury Norov wrote:
> > We took the offending commit via netdev, so I feel responsible. Please
> > LMK if anyone else is planning to apply this fix, otherwise we'll take
> > it and ship it to Linus on Thursday (19th).  
> 
> Please go ahead and add my
> 
> Acked-by: Yury Norov <yury.norov@gmail.com>

Done, thank you!

Re: [PATCH v2] lib/bitmap: Fix bitmap_scatter() and bitmap_gather() kernel doc

Posted by Bagas Sanjaya 1 year, 10 months ago

On Thu, Mar 14, 2024 at 01:00:06PM +0100, Herve Codina wrote:
> diff --git a/include/linux/bitmap.h b/include/linux/bitmap.h
> index fb3a9c93ac86..aa4096126553 100644
> --- a/include/linux/bitmap.h
> +++ b/include/linux/bitmap.h
> @@ -522,17 +522,18 @@ static inline void bitmap_replace(unsigned long *dst,
>   *
>   * (Bits 0, 1, 2, 3, 4, 5 are copied to the bits 0, 1, 4, 8, 9, 12)
>   *
> - * A more 'visual' description of the operation:
> - * src:  0000000001011010
> - *                 ||||||
> - *          +------+|||||
> - *          |  +----+||||
> - *          |  |+----+|||
> - *          |  ||   +-+||
> - *          |  ||   |  ||
> - * mask: ...v..vv...v..vv
> - *       ...0..11...0..10
> - * dst:  0000001100000010
> + * A more 'visual' description of the operation::
> + *
> + *	src:  0000000001011010
> + *	                ||||||
> + *	         +------+|||||
> + *	         |  +----+||||
> + *	         |  |+----+|||
> + *	         |  ||   +-+||
> + *	         |  ||   |  ||
> + *	mask: ...v..vv...v..vv
> + *	      ...0..11...0..10
> + *	dst:  0000001100000010
>   *
>   * A relationship exists between bitmap_scatter() and bitmap_gather().
>   * bitmap_gather() can be seen as the 'reverse' bitmap_scatter() operation.
> @@ -568,16 +569,17 @@ static inline void bitmap_scatter(unsigned long *dst, const unsigned long *src,
>   *
>   * (Bits 0, 1, 4, 8, 9, 12 are copied to the bits 0, 1, 2, 3, 4, 5)
>   *
> - * A more 'visual' description of the operation:
> - * mask: ...v..vv...v..vv
> - * src:  0000001100000010
> - *          ^  ^^   ^   0
> - *          |  ||   |  10
> - *          |  ||   > 010
> - *          |  |+--> 1010
> - *          |  +--> 11010
> - *          +----> 011010
> - * dst:  0000000000011010
> + * A more 'visual' description of the operation::
> + *
> + *	mask: ...v..vv...v..vv
> + *	src:  0000001100000010
> + *	         ^  ^^   ^   0
> + *	         |  ||   |  10
> + *	         |  ||   > 010
> + *	         |  |+--> 1010
> + *	         |  +--> 11010
> + *	         +----> 011010
> + *	dst:  0000000000011010
>   *
>   * A relationship exists between bitmap_gather() and bitmap_scatter(). See
>   * bitmap_scatter() for the bitmap scatter detailed operations.

LGTM, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v2] lib/bitmap: Fix bitmap_scatter() and bitmap_gather() kernel doc

Posted by Andy Shevchenko 1 year, 11 months ago

On Thu, Mar 14, 2024 at 01:00:06PM +0100, Herve Codina wrote:
> The make htmldoc command failed with the following error
>   ... include/linux/bitmap.h:524: ERROR: Unexpected indentation.
>   ... include/linux/bitmap.h:524: CRITICAL: Unexpected section title or transition.
> 
> Move the visual representation to a literal block.

Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

-- 
With Best Regards,
Andy Shevchenko