lib: Add fpi_timeout API documentation

doc/libfprint-docs.xml

@@ -39,6 +39,7 @@
   <part>
     <title>Writing Drivers</title>
     <xi:include href="xml/fpi-ssm.xml"/>
+    <xi:include href="xml/fpi-poll.xml"/>
   </part>
 
   <index id="api-index">

doc/libfprint-sections.txt

@@ -162,3 +162,12 @@ fpi_ssm_get_user_data
 fpi_ssm_get_error
 fpi_ssm_get_cur_state
 </SECTION>
+
+<SECTION>
+<INCLUDE>fpi-poll.h</INCLUDE>
+<FILE>fpi-poll</FILE>
+fpi_timeout
+fpi_timeout_fn
+fpi_timeout_add
+fpi_timeout_cancel
+</SECTION>

libfprint/fpi-poll.c

@@ -64,6 +64,15 @@
  * your main loop.
  */
 
+/**
+ * SECTION:fpi-poll
+ * @title: Timeouts
+ *
+ * Helper functions to schedule a function call to be made after a timeout. This
+ * is useful to avoid making blocking calls while waiting for hardware to answer
+ * for example.
+ */
+
 /* this is a singly-linked list of pending timers, sorted with the timer that
  * is expiring soonest at the head. */
 static GSList *active_timers = NULL;
@@ -93,9 +102,22 @@ static int timeout_sort_fn(gconstpointer _a, gconstpointer _b)
 		return 0;
 }
 
-/* A timeout is the asynchronous equivalent of sleeping. You create a timeout
+/**
+ * fpi_timeout_add:
+ * @msec: the time before calling the function, in milliseconds (1/1000ths of a second)
+ * @callback: function to callback
+ * @data: data to pass to @callback
+ *
+ * A timeout is the asynchronous equivalent of sleeping. You create a timeout
  * saying that you'd like to have a function invoked at a certain time in
- * the future. */
+ * the future.
+ *
+ * Note that you should hold onto the return value of this function to cancel it
+ * use fpi_timeout_cancel(), otherwise the callback could be called while the driver
+ * is being torn down. %NULL is returned on failure.
+ *
+ * Returns: an #fpi_timeout structure
+ */
 struct fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
 	void *data)
 {
@@ -129,6 +151,13 @@ struct fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
 	return timeout;
 }
 
+/**
+ * fpi_timeout_cancel:
+ * @timeout: an #fpi_timeout structure
+ *
+ * Cancels a timeout scheduled with fpi_timeout_add(), and frees the
+ * @timeout structure.
+ */
 void fpi_timeout_cancel(struct fpi_timeout *timeout)
 {
 	G_DEBUG_HERE();

libfprint/fpi-poll.h

@@ -18,8 +18,20 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
+/**
+ * fpi_timeout_fn:
+ * @data: the data passed to fpi_timeout_add()
+ *
+ * The prototype of the callback function for fpi_timeout_add().
+ */
 typedef void (*fpi_timeout_fn)(void *data);
 
+/**
+ * fpi_timeout:
+ *
+ * An opaque structure representing a scheduled function call, created with
+ * fpi_timeout_add().
+ */
 struct fpi_timeout;
 struct fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
 	void *data);