Fix comments so that scripts/kernel-doc doesn't warn, and fix for-loop
style in bitmap_find_free_region().

Signed-off-by: Yury Norov <yury.norov@gmail.com>
---
 lib/bitmap.c | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/lib/bitmap.c b/lib/bitmap.c
index bf6b0eea1af8..76bf79261107 100644
--- a/lib/bitmap.c
+++ b/lib/bitmap.c
@@ -1238,8 +1238,8 @@ void bitmap_fold(unsigned long *dst, const unsigned long *orig,
  * some size '1 << order' (a power of two), aligned to that same
  * '1 << order' power of two.
  *
- * Returns 1 if REG_OP_ISFREE succeeds (region is all zero bits).
- * Returns 0 in all other cases and reg_ops.
+ * Return: 1 if REG_OP_ISFREE succeeds (region is all zero bits).
+ *	   0 in all other cases and reg_ops.
  */
 
 enum {
@@ -1311,14 +1311,14 @@ static int __reg_op(unsigned long *bitmap, unsigned int pos, int order, int reg_
  * a power (@order) of two, aligned to that power of two, which
  * makes the search algorithm much faster.
  *
- * Return the bit offset in bitmap of the allocated region,
+ * Return: the bit offset in bitmap of the allocated region,
  * or -errno on failure.
  */
 int bitmap_find_free_region(unsigned long *bitmap, unsigned int bits, int order)
 {
 	unsigned int pos, end;		/* scans bitmap by regions of size order */
 
-	for (pos = 0 ; (end = pos + (1U << order)) <= bits; pos = end) {
+	for (pos = 0; (end = pos + BIT(order)) <= bits; pos = end) {
 		if (!__reg_op(bitmap, pos, order, REG_OP_ISFREE))
 			continue;
 		__reg_op(bitmap, pos, order, REG_OP_ALLOC);
@@ -1336,8 +1336,6 @@ EXPORT_SYMBOL(bitmap_find_free_region);
  *
  * This is the complement to __bitmap_find_free_region() and releases
  * the found region (by clearing it in the bitmap).
- *
- * No return value.
  */
 void bitmap_release_region(unsigned long *bitmap, unsigned int pos, int order)
 {
@@ -1353,7 +1351,7 @@ EXPORT_SYMBOL(bitmap_release_region);
  *
  * Allocate (set bits in) a specified region of a bitmap.
  *
- * Return 0 on success, or %-EBUSY if specified region wasn't
+ * Return: 0 on success, or %-EBUSY if specified region wasn't
  * free (not all bits were zero).
  */
 int bitmap_allocate_region(unsigned long *bitmap, unsigned int pos, int order)
-- 
2.39.2

On Tue, Aug 15, 2023 at 04:36:21PM -0700, Yury Norov wrote:
> Fix comments so that scripts/kernel-doc doesn't warn, and fix for-loop
> style in bitmap_find_free_region().

Suggested-by?

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

-- 
With Best Regards,
Andy Shevchenko

On Thu, Aug 17, 2023 at 12:39:49PM +0300, Andy Shevchenko wrote:
> On Tue, Aug 15, 2023 at 04:36:21PM -0700, Yury Norov wrote:
> > Fix comments so that scripts/kernel-doc doesn't warn, and fix for-loop
> > style in bitmap_find_free_region().
> 
> Suggested-by?

Can you send a full tag?

> Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> 
> -- 
> With Best Regards,
> Andy Shevchenko
>

On Thu, Aug 17, 2023 at 07:22:25AM -0700, Yury Norov wrote:
> On Thu, Aug 17, 2023 at 12:39:49PM +0300, Andy Shevchenko wrote:
> > On Tue, Aug 15, 2023 at 04:36:21PM -0700, Yury Norov wrote:
> > > Fix comments so that scripts/kernel-doc doesn't warn, and fix for-loop
> > > style in bitmap_find_free_region().
> > 
> > Suggested-by?
> 
> Can you send a full tag?

I thought it's easy to get... Nevertheless it's here.

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

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

Btw, there are things needs to be fixed/improved as well:
1) bitmap_pos_to_ord(): reference to @nbits instead of @bits;
2) bitmap_parse(): wrong/confusing reference to a list, while
   should be better example for under 32-bit input and over it with spaces
   and/or commas;
3) style of the descriptions of the parameters:
     *   @param :
   vs.
     * @param:  /// preferable
4) bitmap_cut(): make nbits a reference as @nbits in some cases;
5) empty line after the function summary (should be dropped),
   e.g. in bitmap_parse_user();
6) true and false can be referred )in bitmap_print_to_buf(), for example)
   as constants %true. %false (up to you).

Maybe something else... That said, the documentation should be revisited
carefully.

-- 
With Best Regards,
Andy Shevchenko