[PATCH 1/2] utils: Document wl_container_of

[Kristian Høgsberg]

On Mon, Sep 16, 2013 at 11:46 AM, Aaron Faanes <dafrito at gmail.com> wrote:
> 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.

This is much better now.

> /**
>  * 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.

Kristian

>  * 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>
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>