[Xcb] about xcb_image

[Barton C Massey]

In message <Pine.LNX.4.64.0803091944550.5181 at grozny.maths.univ-evry.fr> you wrote:
> On Sun, 9 Mar 2008, Barton C Massey wrote:
> > The comment right above 267 that says "when base = 0 && data
> > == 0 && bytes == ~0 we just return the image structure and
> > let the caller deal with getting the allocation right" was
> > deliberate---my intent was that any caller that uses
> > xcb_image_create() this way is responsible for initializing
> > both base and data appropriately for what they're trying to
> > do.  A typical usage of this mode is that you want to do
> > something clever with the allocation, but you want
> > xcb_image_create() to compute the image size for you first.
> 
> that's not very convenient. In that case (base = data =
> NULL, bytes = ~0), the user indeed manages memory
> himself. So data is set by the user and he should free it
> himself. There is no need of base in that case.

That's not necessarily true.  The user may choose to set
base so that her storage may be automatically freed even
though it doesn't start at data.

> So it's  very error-prone to not set the base to NULL in
> xcb_image_create.

I don't agree, but I fixed it anyway. :-)

> Also, the documentation of xcb_image_create does not
> mention that we have to set the base to NULL.

Like I say, that comment, which should probably be moved
into the Doxygen documentation, points out that if you offer
to manage the memory yourself, you're on your own.  It seems
to me clear that you should plan on initializing the
relevant pointers to valid values at that point.

> The doc of xcb_image_destroy mentions that it is freed,
> though (and the doc of that member too), but maybe it
> would be better to mention that in the doc of xcb_create.

The Doxygen could be definitely improved.  I'll try to do it
myself if I get time, but someone might want to beat me to
it.

     Bart