[libvirt] [libvirt-glib 5/5] Add gvir_config_domain_os_get_boot_devices()

[Daniel P. Berrange]

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-icon-list

  "Returns: copy of default icon list. [element-type GdkPixbuf][transfer container]"


IMHO this is sufficient and we don't need to explicitly mention the
transfer rules in the docs string.

Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|