Document XMPPRoster and XMPPRosterDelegate

src/XMPPRoster.h

@@ -30,6 +30,10 @@
 @class XMPPRoster;
 @class XMPPMulticastDelegate;
 
+/**
+ * \brief A protocol that should be (partially) implemented by delegates
+ * 	  of a XMPPRoster
+ */
 @protocol XMPPRosterDelegate
 #ifndef XMPP_ROSTER_M
     <OFObject>
@@ -37,12 +41,27 @@
 #ifdef OF_HAVE_OPTIONAL_PROTOCOLS
 @optional
 #endif
+/**
+ * This callback is called after the roster was received (as a result of
+ * calling -requestRoster.
+ *
+ * \param roster The roster that was received
+ */
 - (void)rosterWasReceived: (XMPPRoster*)roster;
+
+/**
+ * This callback is called whenever a roster push was received.
+ *
+ * \param roster The roster that was updated by the roster push
+ * \param rosterItem The roster item received in the push
+ */
 -         (void)roster: (XMPPRoster*)roster
   didReceiveRosterItem: (XMPPRosterItem*)rosterItem;
 @end
 
-
+/**
+ * \brief A class implementing roster related functionality
+ */
 @interface XMPPRoster: OFObject
 #ifdef OF_HAVE_OPTIONAL_PROTOCOLS
     <XMPPConnectionDelegate>
@@ -53,14 +72,62 @@
 	XMPPMulticastDelegate *delegates;
 }
 
-- initWithConnection: (XMPPConnection*)conn;
+/**
+ * Initializes an already allocated XMPPRoster
+ *
+ * \param connection The connection roster related stanzas
+ *	  are send and received over
+ * \return An initialized XMPPRoster
+ */
+- initWithConnection: (XMPPConnection*)connection;
+
+/**
+ * Returns the list of contacts as a OFDictionary with the bare JID as key
+ *
+ * \return An autoreleased copy of the dictionary containing the roster items
+ */
 - (OFDictionary*)rosterItems;
+
+/**
+ * Requests the roster from the server
+ */
 - (void)requestRoster;
+
+/**
+ * Adds a new contact to the roster
+ *
+ * \param rosterItem The roster item to add to the roster
+ */
 - (void)addRosterItem: (XMPPRosterItem*)rosterItem;
+
+/**
+ * Updates an already existing contact in the roster
+ *
+ * \param rosterItem The roster item to update
+ */
 - (void)updateRosterItem: (XMPPRosterItem*)rosterItem;
+
+/**
+ * Delete a contact from the roster
+ *
+ * \param rosterItem The roster item to delete
+ */
 - (void)deleteRosterItem: (XMPPRosterItem*)rosterItem;
+
+/**
+ * Adds the specified delegate
+ *
+ * \param delegate The delegate to add
+ */
 - (void)addDelegate: (id <XMPPRosterDelegate>)delegate;
+
+/**
+ * Removes the specified delegate
+ *
+ * \param delegate The delegate to remove
+ */
 - (void)removeDelegate: (id <XMPPRosterDelegate>)delegate;
+
 - (void)XMPP_addRosterItem: (XMPPRosterItem*)rosterItem;
 - (void)XMPP_updateRosterItem: (XMPPRosterItem*)rosterItem;
 - (void)XMPP_deleteRosterItem: (XMPPRosterItem*)rosterItem;