changeset 26478:36c435f55252

Large documentation blocks never hurt anyone.

--- a/libpurple/protocols/jabber/iq.h	Sat Apr 04 18:17:58 2009 +0000
+++ b/libpurple/protocols/jabber/iq.h	Sun Apr 05 19:05:49 2009 +0000
@@ -34,10 +34,44 @@
 
 typedef struct _JabberIq JabberIq;
 
+/**
+ * A JabberIqHandler is called to process an incoming IQ stanza.
+ * Handlers typically process unsolicited incoming GETs or SETs for their
+ * registered namespace, but may be called to handle the results of a
+ * GET or SET that we generated if no JabberIqCallback was generated
+ * The handler may be called for the results of a GET or SET (RESULT or ERROR)
+ * that we generated
+ * if the generating function did not register a JabberIqCallback.
+ *
+ * @param js    The JabberStream object.
+ * @param from  The remote entity (the from attribute on the <iq/> stanza)
+ * @param type  The IQ type.
+ * @param id    The IQ id (the id attribute on the <iq/> stanza)
+ * @param child The child element of the <iq/> stanza that matches the name
+ *              and namespace registered with jabber_iq_register_handler.
+ *
+ * @see jabber_iq_register_handler()
+ * @see JabberIqCallback
+ */
 typedef void (JabberIqHandler)(JabberStream *js, const char *from,
                                JabberIqType type, const char *id,
                                xmlnode *child);
 
+/**
+ * A JabberIqCallback is called to process the results of a GET or SET that
+ * we send to a remote entity. The callback is matched based on the id
+ * of the incoming stanza (which matches the one on the initial stanza).
+ *
+ * @param js     The JabberStream object.
+ * @param from   The remote entity (the from attribute on the <iq/> stanza)
+ * @param type   The IQ type. The only possible values are JABBER_IQ_RESULT
+ *               and JABBER_IQ_ERROR.
+ * @param id     The IQ id (the id attribute on the <iq/> stanza)
+ * @param packet The <iq/> stanza
+ * @param data   The callback data passed to jabber_iq_set_callback()
+ *
+ * @see jabber_iq_set_callback()
+ */
 typedef void (JabberIqCallback)(JabberStream *js, const char *from,
                                 JabberIqType type, const char *id,
                                 xmlnode *packet, gpointer data);