Re: [PATCH] qom/object: Comment to use g_slist_free on object_class_get_list result

["Daniel P. Berrangé" <berrange@redhat.com>]

On Fri, Feb 28, 2020 at 11:06:38AM +0100, Marc-André Lureau wrote:
> Hi
> 
> On Fri, Feb 28, 2020 at 10:47 AM Daniel P. Berrangé <berrange@redhat.com> wrote:
> >
> > On Thu, Feb 27, 2020 at 08:09:42PM +0100, Philippe Mathieu-Daudé wrote:
> > > Document the list returned by object_class_get_list() must be
> > > released with g_slist_free() to avoid memory leaks.
> > >
> > > Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> > > ---
> > >  include/qom/object.h | 6 ++++++
> > >  1 file changed, 6 insertions(+)
> > >
> > > diff --git a/include/qom/object.h b/include/qom/object.h
> > > index 29546496c1..5517b56508 100644
> > > --- a/include/qom/object.h
> > > +++ b/include/qom/object.h
> > > @@ -984,6 +984,9 @@ void object_class_foreach(void (*fn)(ObjectClass *klass, void *opaque),
> > >   * @include_abstract: Whether to include abstract classes.
> > >   *
> > >   * Returns: A singly-linked list of the classes in reverse hashtable order.
> > > + *
> > > + * The returned list must be released with g_slist_free()
> > > + * when no longer required.
> >
> > I'd suggest
> >
> >   "The returned list, but not its elements, must be released with
> >    g_slist_free() or g_autoptr when no longer required"
> 
> As gobject-introspection annotations: "Returns: (transfer container)
> (element-type ObjectClass): A list of #ObjectClass"

If we were using Gobject introspection and/or Gtk-Doc, then I'd certainly
suggest that syntax, but AFAIK this is not something that fits with our
intented docs tools. There might be sense in having our docs tools parse
these kind of annotations as it is useful to have it in standardized
format. I think we should decide on this before actually adding them to
the docs though.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|