On Mon, Sep 16, 2013 at 11:46 AM, Aaron Faanes <[email protected]> wrote: > On Mon, Sep 16, 2013 at 12:57 PM, Bill Spitzak <[email protected]> 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 <[email protected]> > > _______________________________________________ > wayland-devel mailing list > [email protected] > http://lists.freedesktop.org/mailman/listinfo/wayland-devel > _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
