[maemo-developers] Hildon-thumbnail's API

[From: Philip Van Hoof]

Dear Hildon developers,


* When you specify a callback, please try to always set "user_data" as
last argument. 

This makes generating language bindings for it far more easy

For example for Vala bindings instead of using a generated binding, the
glue developer needs to change this:

[CCode (cheader_filename = "hildon-thumbnail.h")]
public static delegate void ThumbnailFactoryFinishedCallback
     (Hildon.ThumbnailFactoryHandle handle, void* user_data, Gdk.Pixbuf
     thumbnail, GLib.Error error);

Into this:

[CCode (instance_pos = 1.1)]
public delegate void ThumbnailFactoryFinishedCallback
    (Hildon.ThumbnailFactoryHandle handle, Gdk.Pixbuf? thumbnail,
    GLib.Error error);

And that's just because Vala is very easy to write a binding for. With
things like PyGTK I guess you have to wrap each user of that callback
into a normal one, and call the actual callback in the abnormal way from
that wrap. Quite cumbersome and hard if everybody would write APIs like
that.


* When you make an API, please always use a real GObject instead of
"typedef gpointer HildonThumbnailFactoryHandle" stuff. 

This makes generating language bindings for it far more easy. 

Far far more easy, actually.

* When you make a type, please try to be consistent with naming header 
files and give them the same name as your type's name. For example 
hildon-thumbnail-factory-handle.h if the type is called like 
HildonThumbnailFactoryHandle

Not hildon-thumbnail-factory.h unless you call it HildonThumbnailFactory,
which would have been, by the way, a fine name too (I don't know why 
adding "Handle" to the type's name makes any sense, but okay).

This makes generating language bindings for it far more easy

* When writing gtk-doc comments, please include all arguments:

Not this:

/**
 * hildon_thumbnail_factory_load_custom:
 * @flags: #HildonThumbnailFlags indicating which flags to use to create the thumbnail
 * 
 * ...
 **/

But this:

/**
 * hildon_thumbnail_factory_load_custom:
 * @uri: Thumbnail will be created for this URI
 * @mime_type: MIME type of the resource the URI points to
 * @width: Desired thumbnail width
 * @height: Desired thumbnail height
 * @callback: Function to call when thumbnail creation finished or there was an error
 * @user_data: Optional data passed to the callback
 * @flags: #HildonThumbnailFlags indicating which flags to use to create the thumbnail
 *
 **/

And given what I recommended above, don't put the flags as last, like
how this API ended up becoming, put it in front of user_data or right
after the self.

If the method is a getter for a singleton, GObject libraries usually
call the method something like:

hildon_thumbnail_factory_get or hildon_thumbnail_factory_get_instance


HildonThumbnailFactory*
hildon_thumbnail_factory_get_instance (const gchar *uri, 
                                       const gchar *mime_type, 
                                       guint width, guint height, 
                                       HildonThumbnailFactoryFinishedCallback callback, 
                                       gpointer user_data);


* If you make a GObject-like API, any API, always include the self
pointer:

Not this:

void hildon_thumbnail_factory_move(const gchar *src_uri, 
                                   const gchar *dest_uri);

But this:

void hildon_thumbnail_factory_move(HildonThumbnailFactory *self,
                                   const gchar *src_uri,  
                                   const gchar *dest_uri);


* Etc etc etc



-- 
Philip Van Hoof, freelance software developer
home: me at pvanhoof dot be 
gnome: pvanhoof at gnome dot org 
http://pvanhoof.be/blog
http://codeminded.be