Added documentation

Author: jonstaff

Extensions/XEP-0077/XMPPRegistration.h

@@ -10,14 +10,40 @@
 
 #define _XMPP_REGISTRATION_H
 
-@interface XMPPRegistration : XMPPModule
-{
+@interface XMPPRegistration : XMPPModule {
   XMPPIDTracker *xmppIDTracker;
 }
 
+/**
+* This method will attempt to change the current user's password to the new one provided. The
+* user *MUST* be authenticated for this to work successfully.
+*
+* @see passwordChangeSuccessful:
+* @see passwordChangeFailed:withError:
+*
+* @param newPassword The new password for the user
+*/
 - (BOOL)changePassword:(NSString *)newPassword;
+
+/**
+* This method will attempt to cancel the current user's registration. Later implementations
+* will provide support for handling authentication challenges by the server. For now,
+* simply pass a value of 'nil' in for password, or preferably, use the other cancellation
+* method.
+*
+* @see cancelRegistration
+*/
 - (BOOL)cancelRegistrationUsingPassword:(NSString *)password;
 
+/**
+* This method will attempt to cancel the current user's registration. The user *MUST* be
+* already authenticated for this to work successfully.
+*
+* @see cancelRegistrationSuccessful:
+* @see cancelRegistrationFailed:withError:
+*/
+- (BOOL)cancelRegistration;
+
 @end
 
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -27,10 +53,42 @@
 @protocol XMPPRegistrationDelegate
 @optional
 
+/**
+* Implement this method when calling [regInstance changePassword:]. It will be invoked
+* if the request for changing the user's password is successfully executed and receives a
+* successful response.
+*
+* @param sender XMPPRegistration object invoking this delegate method.
+*/
 - (void)passwordChangeSuccessful:(XMPPRegistration *)sender;
+
+/**
+* Implement this method when calling [regInstance changePassword:]. It will be invoked
+* if the request for changing the user's password is unsuccessfully executed or receives
+* an unsuccessful response.
+*
+* @param sender XMPPRegistration object invoking this delegate method.
+* @param error NSError containing more details of the failure.
+*/
 - (void)passwordChangeFailed:(XMPPRegistration *)sender withError:(NSError *)error;
 
+/**
+* Implement this method when calling [regInstance cancelRegistration] or a variation. It
+* is invoked if the request for canceling the user's registration is successfully
+* executed and receives a successful response.
+*
+* @param sender XMPPRegistration object invoking this delegate method.
+*/
 - (void)cancelRegistrationSuccessful:(XMPPRegistration *)sender;
+
+/**
+* Implement this method when calling [regInstance cancelRegistration] or a variation. It
+* is invoked if the request for canceling the user's registration is unsuccessfully
+* executed or receives an unsuccessful response.
+*
+* @param sender XMPPRegistration object invoking this delegate method.
+* @param error NSError containing more details of the failure.
+*/
 - (void)cancelRegistrationFailed:(XMPPRegistration *)sender withError:(NSError *)error;
 
 @end

Extensions/XEP-0077/XMPPRegistration.m

@@ -28,6 +28,21 @@ - (void)willDeactivate
 #pragma mark Public API
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
+/**
+* This method provides functionality of XEP-0077 3.3 User Changes Password.
+*
+* @link {http://xmpp.org/extensions/xep-0077.html#usecases-changepw}
+*
+* Example 18. Password Change
+*
+* <iq type='set' to='shakespeare.lit' id='change1'>
+*   <query xmlns='jabber:iq:register'>
+*     <username>bill</username>
+*     <password>newpass</password>
+*   </query>
+* </iq>
+*
+*/
 - (BOOL)changePassword:(NSString *)newPassword
 {
   if (![xmppStream isAuthenticated])
@@ -51,9 +66,9 @@ - (BOOL)changePassword:(NSString *)newPassword
                                   child:query];
 
         [xmppIDTracker addID:[iq elementID]
-                           target:self
-                         selector:@selector(handlePasswordChangeQueryIQ:withInfo:)
-                          timeout:60];
+                      target:self
+                    selector:@selector(handlePasswordChangeQueryIQ:withInfo:)
+                     timeout:60];
 
         [xmppStream sendElement:iq];
       }
@@ -67,6 +82,26 @@ - (BOOL)changePassword:(NSString *)newPassword
   return YES;
 }
 
+/**
+* This method provides functionality of XEP-0077 3.2 Entity Cancels an Existing Registration.
+*
+* @link {http://xmpp.org/extensions/xep-0077.html#usecases-cancel}
+*
+* <iq type='set' from='[email protected]/globe' id='unreg1'>
+*   <query xmlns='jabber:iq:register'>
+*     <remove/>
+*   </query>
+* </iq>
+*
+*/
+- (BOOL)cancelRegistration
+{
+  return [self cancelRegistrationUsingPassword:nil];
+}
+
+/**
+* Same as cancelRegistration. Handling authentication challenges is not yet implemented.
+*/
 - (BOOL)cancelRegistrationUsingPassword:(NSString *)password
 {
   // TODO: Handle the scenario of using password
@@ -102,6 +137,9 @@ - (BOOL)cancelRegistrationUsingPassword:(NSString *)password
 #pragma mark - XMPPIDTracker
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
+/**
+* This method handles the response received (or not received) after calling changePassword.
+*/
 - (void)handlePasswordChangeQueryIQ:(XMPPIQ *)iq withInfo:(XMPPBasicTrackingInfo *)info
 {
   dispatch_block_t block = ^{
@@ -140,6 +178,9 @@ - (void)handlePasswordChangeQueryIQ:(XMPPIQ *)iq withInfo:(XMPPBasicTrackingInfo
     dispatch_async(moduleQueue, block);
 }
 
+/**
+* This method handles the response received (or not received) after calling cancelRegistration.
+*/
 - (void)handleRegistrationCancelQueryIQ:(XMPPIQ *)iq withInfo:(XMPPBasicTrackingInfo *)info
 {
   dispatch_block_t block = ^{