cairo_create_ naming (was Re: [cairo] API Shakeup: cairo_output_stream_t and cairo_surface_finish())

[Carl Worth]

On Wed, 04 May 2005 09:28:51 -0700, Keith Packard wrote:
> I think this is confusing; I don't mind the 'steal' verb, but it seems
> like we should reserve it for an unusual operation instead of the
> primary one.

Heh. This reminds me of an anecdote from a friend of mine. He tells of
a programming environment in which a much-used idiom is
"self.dirty". After observing a friend program in this environment for
an extended period of time, he was led to ponder on the psychological
impact of having to type that phrase over and over...

> 
> 	cairo_surface_destroy (cairo_get_target_surface (cr =  cairo_create
> (cairo_image_surface_create (CAIRO_FORMAT_ARGB32, 256, 256)));
> 
> but, I admit this is obscure at best...

Wow. I definitely hope we don't inflict that on beginning users. And
regardless of the naming, this demonstrates quite well the conceptual
burden for comprehending the cairo_create_and_steal operation. There
are rather twisty semantics of reference counting, etc. that would
have to be understood before the user could come to grips with the
first line of code.

> I suggest using 'for' in both cases (and in all other cases as well) as
> it looks better in the xlib case while not looking completely out of
> place in the image case.

I'm also inclined to prefer 'for'. It's not clear to me that 'with'
provides a significantly improved semantic association. But, 'for'
is quite clearly shorter by one character.

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050504/234ecfb0/attachment.pgp