From 06c72d54bedd94b12b9999d764d4ce6668c7b19b Mon Sep 17 00:00:00 2001
From: Bastien Nocera <hadess@hadess.net>
Date: Tue, 22 May 2018 18:44:10 +0200
Subject: [PATCH] poll: Add missing API docs for polling functions

---
 doc/libfprint-sections.txt |  2 ++
 libfprint/fprint.h         | 21 +++++++++++++++++++++
 libfprint/poll.c           |  6 ++++--
 3 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/doc/libfprint-sections.txt b/doc/libfprint-sections.txt
index 6be10c8c..5e3df1ff 100644
--- a/doc/libfprint-sections.txt
+++ b/doc/libfprint-sections.txt
@@ -11,6 +11,8 @@ fp_handle_events_timeout
 fp_handle_events
 fp_get_next_timeout
 fp_get_pollfds
+fp_pollfd_added_cb
+fp_pollfd_removed_cb
 fp_set_pollfd_notifiers
 </SECTION>
 
diff --git a/libfprint/fprint.h b/libfprint/fprint.h
index 20888d63..198d462f 100644
--- a/libfprint/fprint.h
+++ b/libfprint/fprint.h
@@ -299,7 +299,11 @@ void fp_img_free(struct fp_img *img);
 
 /**
  * fp_pollfd:
+ * @fd: a file descriptor
+ * @events: Event flags to poll for from `<poll.h>`
  *
+ * A structure representing a file descriptor and the events to poll
+ * for, as returned by fp_get_pollfds().
  */
 struct fp_pollfd {
 	int fd;
@@ -311,7 +315,24 @@ int fp_handle_events(void);
 size_t fp_get_pollfds(struct fp_pollfd **pollfds);
 int fp_get_next_timeout(struct timeval *tv);
 
+/**
+ * fp_pollfd_added_cb:
+ * @fd: the new file descriptor
+ * @events: events to monitor for, see `<poll.h>` for the possible values
+ *
+ * Type definition for a function that will be called when a new
+ * event source is added. The @events argument is a flag as defined in
+ * `<poll.h>` such as `POLLIN`, or `POLLOUT`. See fp_set_pollfd_notifiers().
+ */
 typedef void (*fp_pollfd_added_cb)(int fd, short events);
+
+/**
+ * fp_pollfd_removed_cb:
+ * @fd: the file descriptor to stop monitoring
+ *
+ * Type definition for a function that will be called when an
+ * event source is removed. See fp_set_pollfd_notifiers().
+ */
 typedef void (*fp_pollfd_removed_cb)(int fd);
 void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
 	fp_pollfd_removed_cb removed_cb);
diff --git a/libfprint/poll.c b/libfprint/poll.c
index fca0f7fc..a3722c64 100644
--- a/libfprint/poll.c
+++ b/libfprint/poll.c
@@ -340,9 +340,11 @@ API_EXPORTED size_t fp_get_pollfds(struct fp_pollfd **pollfds)
 
 /**
  * fp_set_pollfd_notifiers:
- * @added_cb:
- * @removed_cb:
+ * @added_cb: a #fp_pollfd_added_cb callback or %NULL
+ * @removed_cb: a #fp_pollfd_removed_cb callback or %NULL
  *
+ * This sets the callback functions to call for every new or removed
+ * file descriptor used as an event source.
  */
 API_EXPORTED void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
 	fp_pollfd_removed_cb removed_cb)