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

[Kristian Høgsberg]

Owen Taylor wrote:

...

>>>The mapping of basic surface_create functions to cairo_create
>>>convenience functions seems straightforward:
>>>
>>>	cairo_foo_surface_create -> cairo_create_for_foo
>>>
>>>But, the "overloaded" surface create functions are bit trickier:
>>>
>>>	cairo_foo_surface_create_for_bar -> ?
>>>
>>>Perhaps just:
>>>
>>>	cairo_create_for_foo_bar ?
>>
>>This reads to me as "create for (foo bar)", that is, it breaks the 
>>association with the foo backend.  I think it's a good idea to throw in 
>>a preposition to emphasize that foo and bar are distinct.  How about
>>
>>	cairo_create_for_foo_with_bar ?
>>
>>For example
>>
>>	cairo_create_for_image_with_data
> 
> 
> I think the create_for_foo_bar approach works better when you actually
> substitute in for foo and bar.
> 
> Compare:
> 
>  cairo_xlib_surface_create_for_pixmap() => cairo_create_for_xlib_pixmap()
>                                         => cairo_create_for_xlib_with_pixmap()
> 
>  cairo_image_surface_create_for_data() => cairo_create_for_image_data()
>                                        => cairo_create_for_image_with_data()

I agree that both these sound fairly intuitive, but I think the problem 
I have with those names is that "xlib" and "image" are surface names in 
the cairo API.  The always appear as xlib_surface or image_surface 
except for these constructors.  The fact that combining the surface name 
with the type of data given to the constructor yields meaningful names 
such as "xlib pixmap" and "image data" seems accidental and not like 
something that could be made a general rule.  Actually, the naming 
scheme I'd like to propose is:

	cario_create_for_foo_surface_with_bar()

so we get

	cairo_create_for_xlib_surface_with_pixmap()
	cairo_create_for_image_surface_with_data()

which aren't short names, but I think they are very clear and it's 
obvious what kind of surface they create.

> The transformation in the second version in each pair is hard to guess.
> Though maybe the answer here is to rename all the _for_blah() to _with_blah()
> 
>  cairo_xlib_surface_create_with_pixmap()
>  cairo_image_surface_create_with_data()
> 
> aren't bad names... just different from from what we have now. But then
> should it be
> 
>  cairo_create_with_image_with_data()
> 
> ? Or maybe the cairo_create_<blah>_ convenience functions are just a bad 
> idea. 

I don't think they are a bad idea, but if each backend has a couple of 
constructors and we have 5-7 backends, we're going to have an awful lot 
of cairo_t constructors.  As a consequence I don't think we should 
expect to be able to come up with a short and concise name for each 
constructor.

Kristian