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

[Owen Taylor]

[ Replying to a rather old mail that I was rereading ]

On Tue, 2005-03-01 at 22:25 -0500, Kristian Høgsberg wrote:

> >>+void
> >>+cairo_set_target_pdf_as_file (cairo_t	*cr,
> > 
> > 
> > I'm not sure about the "as" naming here. Of course, this will change a
> > bit with the elimination of set_target in favor of cairo_create
> > convenience functions.
> 
> Yeah, I've puzzled a bit over these names...
> 
> > 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()

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. 

(See earlier cairo_create_and_own() proposal, which I'd like more
if I could come up with a better name for it. cairo_create_take_ownership()? 
Long names for functions that are in hello-world examples and are meant to 
be use nested are unpleasant...)

Regards,
						Owen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050313/5aa05fd0/attachment.pgp