[PATCH 1/2] utils: Document wl_container_of

[Aaron Faanes]

On Sun, Sep 15, 2013 at 8:35 PM, Bill Spitzak <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.

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)?

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