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

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.