On Fri, May 11, 2012 at 01:32:34PM +0100, Daniel P. Berrange wrote:
On Fri, May 11, 2012 at 02:27:37PM +0200, Christophe Fergeau wrote:
On Fri, May 11, 2012 at 03:08:06PM +0300, Zeeshan Ali (Khattak) wrote:
The annotation is not supposed to be directly meant for humans, thats why gtk-doc needs to do a better job. i-e the info is already there, just needs translation.
Yep, I don't know if gtk-doc uses the introspection information at all though (to be able to tell which functions should be used to free the container and which function should be used to free its content). In the mean time, I'd feel more comfortable if we explicitly say what should be done to free the returned data since that is one of the thing that I miss the most when using most C APIs
If I look at the docs for GTK, I see GTK-DOC is including details of the annotations:
eg
http://developer.gnome.org/gtk3/stable/GtkWindow.html#gtk-window-get-default...
"Returns: copy of default icon list. [element-type GdkPixbuf][transfer container]"
Forgot to mention that gtk+ also has a note saying how to free the return value, from your link: "The list is a copy and should be freed with g_list_free(), but the pixbufs in the list have not had their reference count incremented. " Christophe