[PATCH 2/4] wayland-server: Document wl_listener

[Kristian Høgsberg]

On Wed, Aug 28, 2013 at 06:02:00PM -0500, Aaron Faanes wrote:
> ---
>  src/wayland-server.h | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/src/wayland-server.h b/src/wayland-server.h
> index d77050d..59fa43a 100644
> --- a/src/wayland-server.h
> +++ b/src/wayland-server.h
> @@ -129,6 +129,15 @@ wl_client_get_object(struct wl_client *client, uint32_t id);
>  void
>  wl_client_post_no_memory(struct wl_client *client);
>  
> +/** \class wl_listener
> + *
> + * \brief A single listener for Wayland events and signals
> + *
> + * Many Wayland events use wl_listener for notification of significant
> + * events, like destruction. Clients should create these objects manually
> + * and register them as listeners using the registration methods (usually
> + * suffixed with "_add" and "_notify") provided by other objects.

This sounds pretty good, though I'd explain that they're always used
with wl_signal and how to add a listener to a signal.  Then explain
that sometimes the wl_signal is in an opaque struct and we provide
accessor functions to add the listener and give a couple of specific
examples.

Finally, maybe add a comment that it's common to embed a listener
struct in a bigger struct and then use wl_container_of to get back to
the bigger struct on the notify callback.

Kristian

> + */
>  struct wl_listener {
>  	struct wl_list link;
>  	wl_notify_func_t notify;
> -- 
> 1.8.3.1
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel