virBitmapToString|virBitmapNewString: Clarify semantics of the 'string'

Clarify which bit is considered most significant in the bitmap and
resulting string. Also be explicit that it's a hex string.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

diff --git a/src/util/virbitmap.c b/src/util/virbitmap.c
index ad5213f216375d43d3189be73a321b7501adbbac..ed28427736854ab2b1267ce3b3f25d6b246d3534 100644 (file)
--- a/src/util/virbitmap.c
+++ b/src/util/virbitmap.c
@@ -328,7 +328,9 @@ virBitmapGetBit(virBitmapPtr bitmap,
  * virBitmapToString:
  * @bitmap: Pointer to bitmap
  *
- * Convert @bitmap to printable string.
+ * Convert @bitmap to a number where the bit with highest position/index in
+ * @bitmap represents the most significant bit and return the number in form
+ * of a hexadecimal string.
  *
  * Returns pointer to the string or NULL on error.
  */
@@ -1117,10 +1119,14 @@ virBitmapCountBits(virBitmapPtr bitmap)
  * virBitmapNewString:
  * @string: the string to be converted to a bitmap
  *
- * Allocate a bitmap from a string of hexadecimal data.
+ * Allocate a bitmap and populate it from @string representing a number in
+ * hexadecimal format. Note that the most significant bit of the number
+ * represented by @string will correspond to the highest index/position in the
+ * bitmap. The size of the returned bitmap corresponds to 4 * the length of
+ * @string.
  *
- * Returns a pointer to the allocated bitmap or NULL if
- * memory cannot be allocated.
+ * Returns a pointer to the allocated bitmap or NULL and reports an error if
+ * @string can't be converted.
  */
 virBitmapPtr
 virBitmapNewString(const char *string)