[PATCH 1/2] utils: Document wl_container_of

[Bill Spitzak]

Aaron Faanes wrote:
> On Sun, Sep 15, 2013 at 8:35 PM, Bill Spitzak <spitzak at gmail.com 
> <mailto:spitzak at gmail.com>> wrote:
>
>     On 09/15/2013 11:09 AM, Aaron Faanes wrote:
>
>         +/**
>         + * Retrieves a pointer to the container of a given item.
>         + *
>         + * This macro allows conversion from a pointer to a contained
>         item to its
>         + * container. This is useful if you have a contained item
>         like a wl_list,
>         + * wl_listener, or wl_signal, and would like to retrieve the
>         struct that
>         + * contains it.
>         + *
>         + * To demonstrate, given a wl_list contained by a wl_resource
>
>
>     I think you might want to add "in a member called 'link'" Without
>     this information it took a bit of puzzling to figure out exactly
>     what was going on.
>
>
> Good point. I'll add that in.
>  
>
>
>         + *
>         + * \code
>         + * struct wl_list *some_link = ...;
>
>
>     I don't know if there are any real examples with a simpler object
>     but the doc is a little confusing by making the inner object a
>     complex one like wl_list. Is there an example where the member is
>     something simple like an int?
>
>
> An int could certainly be used, though I'm not certain if there's any 
> real examples in the code, which is why I hesitate to use a primitive.
I thought that might be a problem. Using a real example is probably a 
good idea.

> What if the example was expanded slightly, like so:
>
> \code
> struct wl_container {
>     wl_list link;
>     ...
> };
>
> struct wl_container container;
> struct wl_list *item = &container.link;
>
> struct wl_container *sample = NULL;
> assert(&container == wl_container_of(item, sample, link);
> \endcode
>
> Does this make it clearer (without making it too verbose)?
No I think it iwas ok as long as the member name is given. Also I would 
perfer an actual example of usage rather than an assert. I would guess 
that most/all users pass the same pointer they are assigning to the 
macro as the pointer-type argument?

ie keep "sample = wl_container_of(item, sample, link)"