changeset 22390:e3bf822c19c8

Document PurpleEventLoopUiOps and associated misc.

--- a/doc/ui-ops.dox	Fri Feb 29 14:47:34 2008 +0000
+++ b/doc/ui-ops.dox	Fri Feb 29 15:45:48 2008 +0000
@@ -10,7 +10,7 @@
    - #PurpleCoreUiOps
    - #PurpleDebugUiOps
    - #PurpleDnsQueryUiOps
-   - #PurpleEventLoopUiOps
+   - #PurpleEventLoopUiOps (without this, nothing will work and you will cry)
    - #PurpleIdleUiOps
    - #PurpleNotifyUiOps
    - #PurplePrivacyUiOps

--- a/libpurple/eventloop.h	Fri Feb 29 14:47:34 2008 +0000
+++ b/libpurple/eventloop.h	Fri Feb 29 15:45:48 2008 +0000
@@ -42,59 +42,108 @@
 
 } PurpleInputCondition;
 
+/** The type of callbacks to handle events on file descriptors, as passed to
+ *  purple_input_add().  The callback will receive the @c user_data passed to
+ *  purple_input_add(), the file descriptor on which the event occurred, and the
+ *  condition that was satisfied to cause the callback to be invoked.
+ */
 typedef void (*PurpleInputFunction)(gpointer, gint, PurpleInputCondition);
 
+/** @copydoc _PurpleEventLoopUiOps */
 typedef struct _PurpleEventLoopUiOps PurpleEventLoopUiOps;
 
+/** An abstraction of an application's mainloop; libpurple will use this to
+ *  watch file descriptors and schedule timed callbacks.  If your application
+ *  uses the glib mainloop, there is an implementation of this struct in
+ *  <tt>libpurple/example/nullclient.c</tt> which you can use verbatim.
+ */
 struct _PurpleEventLoopUiOps
 {
 	/**
-	 * Creates a callback timer with an interval measured in milliseconds.
-	 * @see g_timeout_add, purple_timeout_add
+	 * Should create a callback timer with an interval measured in
+	 * milliseconds.  The supplied @a function should be called every @a
+	 * interval seconds until it returns @c FALSE, after which it should not
+	 * be called again.
+	 *
+	 * Analogous to g_timeout_add in glib.
+	 *
+	 * @param interval the interval in <em>milliseconds</em> between calls
+	 *                 to @a function.
+	 * @param data     arbitrary data to be passed to @a function at each
+	 *                 call.
+	 * @todo Who is responsible for freeing @a data?
+	 *
+	 * @return a handle for the timeout, which can be passed to
+	 *         #timeout_remove.
+	 *
+	 * @see purple_timeout_add
 	 **/
 	guint (*timeout_add)(guint interval, GSourceFunc function, gpointer data);
 
 	/**
-	 * Removes a callback timer.
-	 * @see purple_timeout_remove, g_source_remove
+	 * Should remove a callback timer.  Analogous to g_source_remove in glib.
+	 * @param handle an identifier for a timeout, as returned by
+	 *               #timeout_add.
+	 * @return       @c TRUE if the timeout identified by @a handle was
+	 *               found and removed.
+	 * @see purple_timeout_remove
 	 */
 	gboolean (*timeout_remove)(guint handle);
 
 	/**
-	 * Adds an input handler.
-	 * @see purple_input_add, g_io_add_watch_full
+	 * Should add an input handler.  Analogous to g_io_add_watch_full in
+	 * glib.
+	 *
+	 * @param fd        a file descriptor to watch for events
+	 * @param cond      a bitwise OR of events on @a fd for which @a func
+	 *                  should be called.
+	 * @param func      a callback to fire whenever a relevant event on @a
+	 *                  fd occurs.
+	 * @param user_data arbitrary data to pass to @a fd.
+	 * @return          an identifier for this input handler, which can be
+	 *                  passed to #input_remove.
+	 *
+	 * @see purple_input_add
 	 */
 	guint (*input_add)(int fd, PurpleInputCondition cond,
-					   PurpleInputFunction func, gpointer user_data);
+	                   PurpleInputFunction func, gpointer user_data);
 
 	/**
-	 * Removes an input handler.
-	 * @see purple_input_remove, g_source_remove
+	 * Should remove an input handler.  Analogous to g_source_remove in glib.
+	 * @param handle an identifier, as returned by #input_add.
+	 * @return       @c TRUE if the input handler was found and removed.
+	 * @see purple_input_remove
 	 */
 	gboolean (*input_remove)(guint handle);
 	
 	
 	/**
-	 * Get the current error status for an input.
-	 * Implementation of this UI op is optional. Implement it if the UI's sockets
-	 * or event loop needs to customize determination of socket error status.
-	 * @see purple_input_get_error, getsockopt
+	 * If implemented, should get the current error status for an input.
+	 *
+	 * Implementation of this UI op is optional. Implement it if the UI's
+	 * sockets or event loop needs to customize determination of socket
+	 * error status.  If unimplemented, <tt>getsockopt(2)</tt> will be used
+	 * instead.
+	 *
+	 * @see purple_input_get_error
 	 */
 	int (*input_get_error)(int fd, int *error);
 
 	/**
-	 * Creates a callback timer with an interval measured in seconds.
+	 * If implemented, should create a callback timer with an interval
+	 * measured in seconds.  Analogous to g_timeout_add_seconds in glib.
 	 *
 	 * This allows UIs to group timers for better power efficiency.  For
 	 * this reason, @a interval may be rounded by up to a second.
 	 *
 	 * Implementation of this UI op is optional.  If it's not implemented,
-	 * calls to purple_timeout_add_seconds() will be serviced by the
-	 * timeout_add UI op.
+	 * calls to purple_timeout_add_seconds() will be serviced by
+	 * #timeout_add.
 	 *
-	 * @see g_timeout_add_seconds, purple_timeout_add_seconds()
+	 * @see purple_timeout_add_seconds()
 	 **/
-	guint (*timeout_add_seconds)(guint interval, GSourceFunc function, gpointer data);
+	guint (*timeout_add_seconds)(guint interval, GSourceFunc function,
+	                             gpointer data);
 
 	void (*_purple_reserved2)(void);
 	void (*_purple_reserved3)(void);
@@ -118,8 +167,8 @@
  *                      milliseconds.
  * @param function	The function to call.
  * @param data		data to pass to @a function.
- * @return A handle to the timer which can be passed to 
- *         purple_timeout_remove to remove the timer.
+ * @return A handle to the timer which can be passed to
+ *         purple_timeout_remove() to remove the timer.
  */
 guint purple_timeout_add(guint interval, GSourceFunc function, gpointer data);
 
@@ -137,7 +186,7 @@
  * @param function	The function to call.
  * @param data		data to pass to @a function.
  * @return A handle to the timer which can be passed to 
- *         purple_timeout_remove to remove the timer.
+ *         purple_timeout_remove() to remove the timer.
  *
  * @since 2.1.0
  */
@@ -146,9 +195,9 @@
 /**
  * Removes a timeout handler.
  *
- * @param handle The handle, as returned by purple_timeout_add.
+ * @param handle The handle, as returned by purple_timeout_add().
  *
- * @return Something.
+ * @return @c TRUE if the handler was successfully removed.
  */
 gboolean purple_timeout_remove(guint handle);
 
@@ -164,26 +213,29 @@
  * @see g_io_add_watch_full
  */
 guint purple_input_add(int fd, PurpleInputCondition cond,
-					 PurpleInputFunction func, gpointer user_data);
+                       PurpleInputFunction func, gpointer user_data);
 
 /**
  * Removes an input handler.
  *
  * @param handle The handle of the input handler. Note that this is the return
- * value from purple_input_add, <i>not</i> the file descriptor.
+ *               value from purple_input_add(), <i>not</i> the file descriptor.
  */
 gboolean purple_input_remove(guint handle);
 
 /**
  * Get the current error status for an input.
+ *
  * The return value and error follow getsockopt() with a level of SOL_SOCKET and an
  * option name of SO_ERROR, and this is how the error is determined if the UI does not
  * implement the input_get_error UI op.
  *
  * @param fd        The input file descriptor.
- * @param error		A pointer to an int which on return will have the error, or 0 if no error.
+ * @param error     A pointer to an @c int which on return will have the error, or
+ *                  @c 0 if no error.
  *
- * @return 0 if there is no error; -1 if there is an error, in which case errno will be set.
+ * @return @c 0 if there is no error; @c -1 if there is an error, in which case
+ *         @a errno will be set.
  */
 int
 purple_input_get_error(int fd, int *error);