[PATCH 1/2] utils: Document wl_container_of

[Aaron Faanes]

On Mon, Sep 16, 2013 at 12:57 PM, Bill Spitzak <spitzak at gmail.com> wrote:

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

That's right. Wayland itself uses wl_container_of around ten times, with
all but one using the sample = wl_container_of(item, sample, link) idiom.

How does this doc look? The first two paragraphs were edited; the remainder
is provided for context.

/**
 * 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. 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
 * can be retrieved as follows:
 *
 * \code
 * struct wl_list *some_link = ...;
 * struct wl_resource *resource = NULL;
 *
 * resource = wl_container_of(some_link, resource, link);
 * \endcode
 (the rest is unchanged)

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