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

[Kristian Høgsberg]

On Sun, Sep 15, 2013 at 01:09:18PM -0500, Aaron Faanes wrote:
> This patch takes Kristian's comments into account, adding a demonstration and
> giving a more thorough idea of how wl_listener is used.

This looks fine.  I'd rather see

	/* Direct access */

instead of

	// Direct access

but we can't nest the /* */ style comments.  I've applied it as is,
but if doxygen has some kind of escape mechanism, I'd like to use that
to use /* */ style comments.

thanks,
Kristian

> ---
>  src/wayland-server.h | 45 +++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 45 insertions(+)
> 
> diff --git a/src/wayland-server.h b/src/wayland-server.h
> index 67f3bdd..f345d2a 100644
> --- a/src/wayland-server.h
> +++ b/src/wayland-server.h
> @@ -129,6 +129,51 @@ 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 signals
> + *
> + * wl_listener provides the means to listen for wl_signal notifications. Many
> + * Wayland objects use wl_listener for notification of significant events like
> + * object destruction.
> + *
> + * Clients should create wl_listener objects manually and can register them as
> + * listeners to signals using #wl_signal_add, assuming the signal is
> + * directly accessible. For opaque structs like wl_event_loop, adding a
> + * listener should be done through provided accessor methods. A listener can
> + * only listen to one signal at a time.
> + *
> + * \code
> + * struct wl_listener your_listener;
> + * your_listener.notify = your_callback_method;
> + *
> + * // Direct access
> + * wl_signal_add(&some_object->destroy_signal, &your_listener);
> + *
> + * // Accessor access
> + * wl_event_loop *loop = ...;
> + * wl_event_loop_add_destroy_listener(loop, &your_listener);
> + * \endcode
> + *
> + * If the listener is part of a larger struct, #wl_container_of can be used
> + * to retrieve a pointer to it:
> + *
> + * \code
> + * void your_listener(struct wl_listener *listener, void *data)
> + * {
> + * 	struct your_data *data = NULL;
> + * 	your_data = wl_container_of(listener, data, your_member_name);
> + * }
> + * \endcode
> + *
> + * If you need to remove a listener from a signal, use #wl_list_remove.
> + *
> + * \code
> + * wl_list_remove(&your_listener.link);
> + * \endcode
> + *
> + * \sa wl_signal
> + */
>  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