documentation: kernel-api: add more info on bitmap functions

There are some good comments about bitmap operations in lib/bitmap.c
and include/linux/bitmap.h, so format them for document generation and
pull them into core-api/kernel-api.rst.

I converted the "tables" of functions from using tabs to using spaces
so that they are more readable in the source file and in the generated
output.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/core-api/kernel-api.rst

@@ -53,6 +53,18 @@ The Linux kernel provides more basic utility functions.
 Bitmap Operations
 -----------------
 
+.. kernel-doc:: lib/bitmap.c
+   :doc: bitmap introduction
+
+.. kernel-doc:: include/linux/bitmap.h
+   :doc: declare bitmap
+
+.. kernel-doc:: include/linux/bitmap.h
+   :doc: bitmap overview
+
+.. kernel-doc:: include/linux/bitmap.h
+   :doc: bitmap bitops
+
 .. kernel-doc:: lib/bitmap.c
    :export:
 

include/linux/bitmap.h

@@ -21,13 +21,17 @@
  * See lib/bitmap.c for more details.
  */
 
-/*
+/**
+ * DOC: bitmap overview
+ *
  * The available bitmap operations and their rough meaning in the
  * case that the bitmap is a single unsigned long are thus:
  *
  * Note that nbits should be always a compile time evaluable constant.
  * Otherwise many inlines will generate horrible code.
  *
+ * ::
+ *
  *  bitmap_zero(dst, nbits)                     *dst = 0UL
  *  bitmap_fill(dst, nbits)                     *dst = ~0UL
  *  bitmap_copy(dst, src, nbits)                *dst = *src
@@ -61,10 +65,13 @@
  *  bitmap_allocate_region(bitmap, pos, order)  Allocate specified bit region
  *  bitmap_from_u32array(dst, nbits, buf, nwords)  *dst = *buf (nwords 32b words)
  *  bitmap_to_u32array(buf, nwords, src, nbits) *buf = *dst (nwords 32b words)
+ *
  */
 
-/*
+/**
- * Also the following operations in asm/bitops.h apply to bitmaps.
+ * DOC: bitmap bitops
+ *
+ * Also the following operations in asm/bitops.h apply to bitmaps.::
  *
  *  set_bit(bit, addr)                  *addr |= bit
  *  clear_bit(bit, addr)                *addr &= ~bit
@@ -77,9 +84,11 @@
  *  find_first_bit(addr, nbits)         Position first set bit in *addr
  *  find_next_zero_bit(addr, nbits, bit)  Position next zero bit in *addr >= bit
  *  find_next_bit(addr, nbits, bit)     Position next set bit in *addr >= bit
+ *
  */
 
-/*
+/**
+ * DOC: declare bitmap
  * The DECLARE_BITMAP(name,bits) macro, in linux/types.h, can be used
  * to declare an array named 'name' of just enough unsigned longs to
  * contain all bit positions from 0 to 'bits' - 1.

lib/bitmap.c

@@ -18,7 +18,9 @@
 
 #include <asm/page.h>
 
-/*
+/**
+ * DOC: bitmap introduction
+ *
  * bitmaps provide an array of bits, implemented using an an
  * array of unsigned longs.  The number of valid bits in a
  * given bitmap does _not_ need to be an exact multiple of