[PATCH] docs: Add documentation for wl_event_source callbacks

[chris at cooperteam.net]

From: Christopher James Halse Rogers <christopher.halse.rogers at canonical.com>

Signed-off-by: Christopher James Halse Rogers <christopher.halse.rogers at canonical.com>
---
 src/wayland-server-core.h | 59 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/src/wayland-server-core.h b/src/wayland-server-core.h
index 61da8ab..0a2c689 100644
--- a/src/wayland-server-core.h
+++ b/src/wayland-server-core.h
@@ -43,9 +43,68 @@ enum {
 	WL_EVENT_ERROR    = 0x08
 };
 
+/** Callback for fd-based wl_event_source
+ *
+ * \param fd	The fd that this wl_event_source watches
+ * \param mask	Event mask of the wakeup trigger
+ * \param data	Userdata that was passed to wl_event_loop_add_fd
+ *
+ * \return	Ignored, unless this source has been registered with
+ * 		wl_event_source_check().
+ *
+ * 		If triggered from the post-dispatch check, returning non-zero
+ * 		will influence whether or not checked sources will be
+ * 		immediately checked again.
+ *
+ *		The return values all checked sources will be accumulated;
+ *		if their sum is > 0 all checked sources will be re-checked.
+ */
 typedef int (*wl_event_loop_fd_func_t)(int fd, uint32_t mask, void *data);
+/** Callback for timer wl_event_source
+ *
+ * \param data	Userdata that was passed to wl_event_loop_add_timer()
+ *
+ * \return	Ignored, unless this source has been registered with
+ * 		wl_event_source_check().
+ *
+ * 		If triggered from the post-dispatch check, returning non-zero
+ * 		will influence whether or not checked sources will be
+ * 		immediately checked again.
+ *
+ *		The return values all checked sources will be accumulated;
+ *		if their sum is > 0 all checked sources will be re-checked.
+ */
 typedef int (*wl_event_loop_timer_func_t)(void *data);
+/** Callback for signal-based wl_event_source
+ *
+ * \param signal_number	Signal number that triggered this wakeup
+ * \param data		Userdata that was passed to wl_event_loop_add_signal
+ *
+ * \return	Ignored, unless this source has been registered with
+ * 		wl_event_source_check().
+ *
+ * 		If triggered from the post-dispatch check, returning non-zero
+ * 		will influence whether or not checked sources will be
+ * 		immediately checked again.
+ *
+ *		The return values all checked sources will be accumulated;
+ *		if their sum is > 0 all checked sources will be re-checked.
+ */
 typedef int (*wl_event_loop_signal_func_t)(int signal_number, void *data);
+/** Callback for idle wl_event_source
+ *
+ * \param data	Userdata that was passed to wl_event_loop_add_fd
+ *
+ * \return	Ignored, unless this source has been registered with
+ * 		wl_event_source_check().
+ *
+ * 		If triggered from the post-dispatch check, returning non-zero
+ * 		will influence whether or not checked sources will be
+ * 		immediately checked again.
+ *
+ *		The return values all checked sources will be accumulated;
+ *		if their sum is > 0 all checked sources will be re-checked.
+ */
 typedef void (*wl_event_loop_idle_func_t)(void *data);
 
 struct wl_event_loop *
-- 
2.14.1