cpw.darkrain42.xmpp.iq-handlers: 8baab3f2: Large documentation blocks never hurt an...

[paul at darkrain42.org]

-----------------------------------------------------------------
Revision: 8baab3f2fe55a6921be5c56704bd08ca481c7432
Ancestor: 00cdf30dd298068dea044cabb9760631600b3f97
Author: paul at darkrain42.org
Date: 2009-04-05T19:05:49
Branch: im.pidgin.cpw.darkrain42.xmpp.iq-handlers
URL: http://d.pidgin.im/viewmtn/revision/info/8baab3f2fe55a6921be5c56704bd08ca481c7432

Modified files:
        libpurple/protocols/jabber/iq.h

ChangeLog: 

Large documentation blocks never hurt anyone.

-------------- next part --------------
============================================================
--- libpurple/protocols/jabber/iq.h	d86e1424452579e501fb15b60f6837ddc2a1763d
+++ libpurple/protocols/jabber/iq.h	3da2757e4da6e968ddaf8755077567eb4f3bd365
@@ -34,10 +34,44 @@ typedef struct _JabberIq JabberIq;
 
 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);