[PATCH 3/4] wayland-server: Document wl_signal

[Kristian Høgsberg]

On Wed, Aug 28, 2013 at 06:02:01PM -0500, Aaron Faanes wrote:

This all sounds good, thanks.

Kristian

> ---
>  src/wayland-server.h | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/src/wayland-server.h b/src/wayland-server.h
> index 59fa43a..0e662de 100644
> --- a/src/wayland-server.h
> +++ b/src/wayland-server.h
> @@ -143,22 +143,52 @@ struct wl_listener {
>  	wl_notify_func_t notify;
>  };
>  
> +/** \class wl_signal
> + *
> + * \brief A source of a type of observable event
> + *
> + * Signals are recognized points where significant events can be observed.
> + * Compositors as well as the server can provide signals. Observers are
> + * added through \ref wl_signal_add.
> + */
>  struct wl_signal {
>  	struct wl_list listener_list;
>  };
>  
> +/** Initialize a new \ref wl_signal for use.
> + *
> + * \param signal The signal that will be initialized
> + *
> + * \memberof wl_signal
> + */
>  static inline void
>  wl_signal_init(struct wl_signal *signal)
>  {
>  	wl_list_init(&signal->listener_list);
>  }
>  
> +/** Add the specified listener to this signal.
> + *
> + * \param signal The signal that will emit events to the listener
> + * \param listener The listener to add
> + *
> + * \memberof wl_signal
> + */
>  static inline void
>  wl_signal_add(struct wl_signal *signal, struct wl_listener *listener)
>  {
>  	wl_list_insert(signal->listener_list.prev, &listener->link);
>  }
>  
> +/** Gets the list item for the specified listener.
> + *
> + * \param signal The signal that contains the specified listener
> + * \param notify The listener that is the target of this search
> + * \return the list item that corresponds to the specified listener, or NULL
> + * if none was found
> + *
> + * \memberof wl_signal
> + */
>  static inline struct wl_listener *
>  wl_signal_get(struct wl_signal *signal, wl_notify_func_t notify)
>  {
> @@ -171,6 +201,13 @@ wl_signal_get(struct wl_signal *signal, wl_notify_func_t notify)
>  	return NULL;
>  }
>  
> +/** Emits this signal, notifying all registered listeners.
> + *
> + * \param signal The signal object that will emit the signal
> + * \param data The data that will be emitted with the signal
> + *
> + * \memberof wl_signal
> + */
>  static inline void
>  wl_signal_emit(struct wl_signal *signal, void *data)
>  {
> -- 
> 1.8.3.1
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel