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

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

[Herve Codina]

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.

Signed-off-by: Herve Codina <herve.codina@bootlin.com>
---

This patch fixes de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
available in net-next and linux-next

 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 049ba20911c5..ac87c8292f08 100644
--- a/include/linux/bitmap.h
+++ b/include/linux/bitmap.h
@@ -507,17 +507,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.
@@ -553,16 +554,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] lib/bitmap: Fix bitmap_scatter() and bitmap_gather() kernel doc

[Andy Shevchenko]

On Tue, Mar 12, 2024 at 09:54:03AM +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.

...

> This patch fixes de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
> available in net-next and linux-next

Not sure about rules of net-next, but I would add Fixes FWIW:

Fixes: de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")

-- 
With Best Regards,
Andy Shevchenko

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

[Andy Shevchenko]

On Tue, Mar 12, 2024 at 05:42:11PM +0200, Andy Shevchenko wrote:
> On Tue, Mar 12, 2024 at 09:54:03AM +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.

...

> > This patch fixes de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
> > available in net-next and linux-next
> 
> Not sure about rules of net-next, but I would add Fixes FWIW:
> 
> Fixes: de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")

And probably Reported-by...

-- 
With Best Regards,
Andy Shevchenko

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

[Herve Codina]

Hi Andy,

On Tue, 12 Mar 2024 17:43:00 +0200
Andy Shevchenko <andriy.shevchenko@linux.intel.com> wrote:

> On Tue, Mar 12, 2024 at 05:42:11PM +0200, Andy Shevchenko wrote:
> > On Tue, Mar 12, 2024 at 09:54:03AM +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.  
> 
> ...
> 
> > > This patch fixes de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
> > > available in net-next and linux-next  
> > 
> > Not sure about rules of net-next, but I would add Fixes FWIW:
> > 
> > Fixes: de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")

I think I cannot add the Fixes tag as the de5f84338970 commit is not yet
merged in Torvald's tree and I am not sure that the commit hash will not
change during the merge process.
  
> 
> And probably Reported-by...
> 

Regards,
Hervé

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

[Florian Fainelli]

On 3/12/24 09:35, Herve Codina wrote:
> Hi Andy,
> 
> On Tue, 12 Mar 2024 17:43:00 +0200
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> wrote:
> 
>> On Tue, Mar 12, 2024 at 05:42:11PM +0200, Andy Shevchenko wrote:
>>> On Tue, Mar 12, 2024 at 09:54:03AM +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.
>>
>> ...
>>
>>>> This patch fixes de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
>>>> available in net-next and linux-next
>>>
>>> Not sure about rules of net-next, but I would add Fixes FWIW:
>>>
>>> Fixes: de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
> 
> I think I cannot add the Fixes tag as the de5f84338970 commit is not yet
> merged in Torvald's tree and I am not sure that the commit hash will not
> change during the merge process.

That is not a reason for not providing a Fixes tag, it does not have to 
be in Linus' tree.

As a matter of fact, let us consider someone doing a back port of your 
patches into their custom local tree, they would like to have that 
information that this patch fixes a problem introduced by an earlier 
commit so they can take the entire set of commits as a whole.
-- 
Florian

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

[Andy Shevchenko]

On Tue, Mar 12, 2024 at 05:35:56PM +0100, Herve Codina wrote:
> On Tue, 12 Mar 2024 17:43:00 +0200
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> wrote:
> > On Tue, Mar 12, 2024 at 05:42:11PM +0200, Andy Shevchenko wrote:
> > > On Tue, Mar 12, 2024 at 09:54:03AM +0100, Herve Codina wrote:  

...

> > > Not sure about rules of net-next, but I would add Fixes FWIW:
> > > 
> > > Fixes: de5f84338970 ("lib/bitmap: Introduce bitmap_scatter() and bitmap_gather() helpers")
> 
> I think I cannot add the Fixes tag as the de5f84338970 commit is not yet
> merged in Torvald's tree and I am not sure that the commit hash will not
> change during the merge process.

It may change if and only if there will be rebase done. For the merge the SHA
will be kept the same.

> > And probably Reported-by...

-- 
With Best Regards,
Andy Shevchenko