[libvirt] [PATCHv2 1/7] util: Fix docs for virBitmapParse
Daniel P. Berrange
berrange at redhat.com
Wed Jan 23 14:28:33 UTC 2013
On Tue, Jan 22, 2013 at 03:25:04PM -0700, Eric Blake wrote:
> 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.
In other words it is a "terminator", rather than a "separator". Passing
'0' is basically indicating that the string is NULL terminated.
Daniel
--
|: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org -o- http://virt-manager.org :|
|: http://autobuild.org -o- http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
More information about the libvir-list
mailing list