[PATCH 1/2] utils: Document wl_container_of

[Aaron Faanes]

---

Here's the updated patch. Thanks, Bill and Kristian, for your reviews. Feel
free to let me know if anything else needs correcting with this one.

 src/wayland-util.h | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/wayland-util.h b/src/wayland-util.h
index de2e464..bed8d2a 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 containing struct of a given member item.
+ *
+ * This macro allows conversion from a pointer to a item 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 in a member
+ * called link, 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
+ *
+ * \param ptr A valid pointer to the contained item.
+ *
+ * \param sample A pointer to the type of content that the list item
stores.
+ * Sample does not need be a valid pointer; a null pointer will suffice.
+ *
+ * \param member The named location of ptr within the sample type.
+ *
+ * \return The container for the specified pointer.
+ */
 #ifdef __GNUC__
 #define wl_container_of(ptr, sample, member)                           \
        (__typeof__(sample))((char *)(ptr)      -                       \
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20130916/16048455/attachment.html>