[PATCH 1/2] utils: Document wl_container_of

[Aaron Faanes]

On Mon, Sep 16, 2013 at 11:12 PM, Kristian Høgsberg <krh at bitplanet.net>wrote:

> > /**
> >  * Retrieves a pointer to the containing struct of a given member item.
> >  *
> >  * This macro allows conversion from a pointer to a item, in a member
> called
> >  * link, to its containing struct.
>
> I think the 'in a member called link' phrase is a little odd, here,
> since we've not introduced anything called link.  We're better off
> just leaving that out here, and then spelling it out in the example
> below.
>
> > This is useful if you have a contained
> > item
> >  * like a wl_list, wl_listener, or wl_signal, provided via a callback or
> > other
> >  * means and would like to retrieve the struct that contains it.
> >  *
> >  * To demonstrate, given a wl_list contained by a wl_resource, the
> > wl_resource
>
> I would prefer an example that defines an example struct with a
> wl_list or wl_listener in it and then shows how to get from a pointer
> to that member to the containing struct.  Using wl_resource is a
> little confusing, since it's an opaque struct and can't be used with
> wl_container_of outside the wayland libraries.
>

Perhaps an example like this?

 * \code
 * struct foo_container {
 *     struct wl_listener destroy_listener;
 *     ... other members ...
 * };
 *
 * void foo_container_destroy(struct wl_listener *listener, void *data)
 * {
 *     struct foo_container *container = NULL;
 *     my_foo = wl_container_of(listener, my_foo, destroy_listener);
 *
 *     ... destroy my_foo ...
 * }
 * \endcode

-- 
Aaron Faanes <dafrito at gmail.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20130916/22ada556/attachment-0001.html>