[libvirt] [PATCHv2 1/7] util: Fix docs for virBitmapParse

[Eric Blake]

On 01/22/2013 02:30 PM, Peter Krempa wrote:
> The documentation comment virBitmapParse didn't document the @sep
> parameter.
> ---
>  src/util/virbitmap.c | 16 +++++++++-------
>  1 file changed, 9 insertions(+), 7 deletions(-)
> 
> diff --git a/src/util/virbitmap.c b/src/util/virbitmap.c
> index ca82d1b..e3ca4ff 100644
> --- a/src/util/virbitmap.c
> +++ b/src/util/virbitmap.c
> @@ -265,23 +265,25 @@ char *virBitmapFormat(virBitmapPtr bitmap)
>  /**
>   * virBitmapParse:
>   * @str: points to a string representing a human-readable bitmap
> + * @sep: separator character
>   * @bitmap: a bitmap created from @str
>   * @bitmapSize: the upper limit of num of bits in created bitmap
>   *
>   * This function is the counterpart of virBitmapFormat. This function creates
>   * a bitmap, in which bits are set according to the content of @str.
>   *
> - * @str is a comma separated string of fields N, which means a number of bit
> - * to set, and ^N, which means to unset the bit, and N-M for ranges of bits
> - * to set.
> + * @str is a string of fields N separated by a character @sep, which means a
> + * number of bit to set, and ^N, which means to unset the bit, and N-M for
> + * ranges of bits to set.

This wording confused me.  @sep isn't between each field, so much as at
the end of all of the fields.  Most callers pass 0, but there are some
callers that pass ',' and even one that passes 'n'; so the use of 'sep'
is when you are parsing a bitmap out of a larger string, and want to
stop at the separator that says where the bitmap ends and the rest of
the string continues (and NOT that it separates fields, unless 'sep'
happens to be ',' to parse exactly one field).

But I don't know if I have any better wording, so weak ACK, especially
if you can improve it.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 621 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20130122/f4330be8/attachment-0001.sig>