[PATCH 1/2] utils: Document wl_container_of

[Kristian Høgsberg]

On Mon, Sep 16, 2013 at 11:38:28PM -0500, Aaron Faanes wrote:
> 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?

Exactly, something like that, but a few nit-picks below.

>  * \code
>  * struct foo_container {
>  *     struct wl_listener destroy_listener;
>  *     ... other members ...
>  * };

I use foo and bar all the time informally, but I would avoid using
'foo' in actual documentation.  Maybe example_container?

>  *
>  * 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);

and for the code example, I'd like a blank line between variable
declarations and code, like we do in the actual code.

thanks,
Kritian

>  *
>  *     ... destroy my_foo ...
>  * }
>  * \endcode
> 
> -- 
> Aaron Faanes <dafrito at gmail.com>