[PATCH 1/2] utils: Document wl_container_of

[Bill Spitzak]

On 09/15/2013 11:09 AM, Aaron Faanes wrote:
> Modified this documentation to be much less verbose than before. I also added
> an example, used better doxygen style, and mentioned that wl_container_of is
> useful outside of just wl_list.
>
> ---
>   src/wayland-util.h | 27 +++++++++++++++++++++++++++
>   1 file changed, 27 insertions(+)
>
> diff --git a/src/wayland-util.h b/src/wayland-util.h
> index de2e464..f85c521 100644
> --- a/src/wayland-util.h
> +++ b/src/wayland-util.h
> @@ -111,6 +111,33 @@ int wl_list_length(const struct wl_list *list);
>   int wl_list_empty(const struct wl_list *list);
>   void wl_list_insert_list(struct wl_list *list, struct wl_list *other);
>
> +/**
> + * 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.

> + *
> + * \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?