[PATCH 03/15] virBitmapToString|virBitmapNewString: Clarify semantics of the 'string'

[Peter Krempa]

On Fri, Oct 02, 2020 at 13:17:17 +0200, Ján Tomko wrote:
> On a Friday in 2020, Peter Krempa wrote:
> > 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 at redhat.com>
> > ---
> > src/util/virbitmap.c | 13 +++++++++----
> > 1 file changed, 9 insertions(+), 4 deletions(-)
> > 
> > diff --git a/src/util/virbitmap.c b/src/util/virbitmap.c
> > index ad5213f216..fcb8e1101a 100644
> > --- 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 printable hexadecimal string representation. Note that bit
> > + * with highest position/index in @bitmap are considered as most significant bit
> > + * in the output string.
> 
> the bits ... are considered
>  or
> the bit ... is considered

oops, I've rewrote it halfway through ...

> 
> would mentioning that it is printed at the leftmost position be clearer?

Well, the thing is that the leftmost digit in the output string
represents more than one bit since it's hex. I thought about some
wordign but couldn't come up with anything more appropriate.

We could do: 'is considered as the most significant bit of the number
represented by the output string', or just 'most significant bit of the
output number". That way the reader knows it's a number and the
semantics of the bit are then implicit.