Documentation for POP Objective-C API.

7 files changed, 87 insertions, 3 deletions

diff --git a/src/objc/pop/MCOPOPFetchHeaderOperation.h b/src/objc/pop/MCOPOPFetchHeaderOperation.h
index f9dba7f5..b062904a 100644
--- a/src/objc/pop/MCOPOPFetchHeaderOperation.h
+++ b/src/objc/pop/MCOPOPFetchHeaderOperation.h
@@ -13,6 +13,9 @@
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOPOPOperation.h>
 
+// This is an asynchronous operation that will fetch the header of a message.
+// See MCOPOPSession for more info.
+
 @class MCOMessageHeader;
 
 @interface MCOPOPFetchHeaderOperation : MCOPOPOperation
diff --git a/src/objc/pop/MCOPOPFetchMessageOperation.h b/src/objc/pop/MCOPOPFetchMessageOperation.h
index f833a1cc..56857a73 100644
--- a/src/objc/pop/MCOPOPFetchMessageOperation.h
+++ b/src/objc/pop/MCOPOPFetchMessageOperation.h
@@ -13,10 +13,14 @@
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOPOPOperation.h>
 
+// This is an asynchronous operation that will fetch the content of a message.
+
 typedef void (^MCOPOPOperationProgressBlock)(unsigned int current, unsigned int maximum);
 
 @interface MCOPOPFetchMessageOperation : MCOPOPOperation
 
+// This block will be called during the progression of the download of the message
+// when some bytes have been downloaded from the network.
 @property (nonatomic, copy) MCOPOPOperationProgressBlock progress;
 
 - (void)start:(void (^)(NSError *error, NSData * messageData))completionBlock;
diff --git a/src/objc/pop/MCOPOPFetchMessagesOperation.h b/src/objc/pop/MCOPOPFetchMessagesOperation.h
index 40cc175c..ffbf623b 100644
--- a/src/objc/pop/MCOPOPFetchMessagesOperation.h
+++ b/src/objc/pop/MCOPOPFetchMessagesOperation.h
@@ -13,6 +13,8 @@
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOPOPOperation.h>
 
+// This is an asynchronous operation that will fetch the list of a messages on the account.
+
 @interface MCOPOPFetchMessagesOperation : MCOPOPOperation
 
 - (void)start:(void (^)(NSError *error, NSArray * messages))completionBlock;
diff --git a/src/objc/pop/MCOPOPMessageInfo.h b/src/objc/pop/MCOPOPMessageInfo.h
index 5c6b529f..06cc23c1 100644
--- a/src/objc/pop/MCOPOPMessageInfo.h
+++ b/src/objc/pop/MCOPOPMessageInfo.h
@@ -8,10 +8,18 @@
 
 #import <Foundation/Foundation.h>
 
+// This is information of a message fetched by MCOPOPFetchMessagesOperation.
+
 @interface MCOPOPMessageInfo : NSObject <NSCopying>
 
+// This is the index of a given message.
 @property (nonatomic, assign) unsigned int index;
+
+// This is the size of the given message.
 @property (nonatomic, assign) unsigned int size;
+
+// This is the unique identifier of the message.
+// It can be used as a cache identifier.
 @property (nonatomic, copy) NSString * uid;
 
 @end
diff --git a/src/objc/pop/MCOPOPOperation.h b/src/objc/pop/MCOPOPOperation.h
index 3b482fdf..9eaf7fff 100644
--- a/src/objc/pop/MCOPOPOperation.h
+++ b/src/objc/pop/MCOPOPOperation.h
@@ -13,6 +13,9 @@
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOOperation.h>
 
+// This is an asynchronous POP3 operation.
+// See MCOPOPSession for more info.
+
 @interface MCOPOPOperation : MCOOperation
 - (void)start:(void (^)(NSError *error))completionBlock;
 @end
diff --git a/src/objc/pop/MCOPOPSession.h b/src/objc/pop/MCOPOPSession.h
index 81ae2e86..7b59256d 100644
--- a/src/objc/pop/MCOPOPSession.h
+++ b/src/objc/pop/MCOPOPSession.h
@@ -20,23 +20,87 @@
 @class MCOPOPOperation;
 @class MCOIndexSet;
 
+// This class implements asynchronous POP3 protocol.
+
 @interface MCOPOPSession : NSObject
 
+// This is the hostname of the POP3 server to connect to.
 @property (nonatomic, copy) NSString * hostname;
+
+// This is the port of the POP3 server to connect to.
 @property (nonatomic, assign) unsigned int port;
+
+// This is the username of the account.
 @property (nonatomic, copy) NSString * username;
+
+// This is the password of the account.
 @property (nonatomic, copy) NSString * password;
+
+// This is the authentication type to use to connect.
+// MCOAuthTypeSASLNone means that it uses the clear-text password authentication.
+// It's the default.
+// Note: However, over a encrypted connection, the password will be safe.
 @property (nonatomic, assign) MCOAuthType authType;
+
+// This is the encryption type to use.
+// See MCOConnectionType for more information.
 @property (nonatomic, assign) MCOConnectionType connectionType;
+
+// This is the timeout of the connection.
 @property (nonatomic, assign) NSTimeInterval timeout;
+
+// When set to YES, the connection will fail if the certificate is incorrect.
 @property (nonatomic, assign, getter=isCheckCertificateEnabled) BOOL checkCertificateEnabled;
 
+// Returns an operation that will fetch the list of messages.
+//
+// {
+//   ...
+//   MCOPOPFetchMessagesOperation * op [session fetchMessagesOperation];
+//   [op start:^(NSError *error, NSArray * messages) {
+//      // messages is an array of MCOPOPMessageInfo
+//      // [info index] can be used as reference for a given message in the other operations.
+//   }]];
+//
 - (MCOPOPFetchMessagesOperation *) fetchMessagesOperation;
+
+// Returns an operation that will fetch the header of the given message.
+//
+// {
+//   ...
+//   MCOPOPFetchHeaderOperation * op [session fetchHeaderOperationWithIndex:idx];
+//   [op start:^(NSError *error, MCOMessageHeader * header) {
+//        // header is the parsed header of the message.
+//   }]];
+//
 - (MCOPOPFetchHeaderOperation *) fetchHeaderOperationWithIndex:(unsigned int)index;
+
+// Returns an operation that will fetch the content of the given message.
+//
+// {
+//   ...
+//   MCOPOPFetchMessageOperation * op [session fetchMessageOperationWithIndex:idx];
+//   [op start:^(NSError *error, NSData * messageData) {
+//        // messageData is the RFC 822 formatted message data.
+//   }]];
+//
 - (MCOPOPFetchMessageOperation *) fetchMessageOperationWithIndex:(unsigned int)index;
 
-// Will disconnect.
-- (MCOPOPOperation *) deleteMessagesWithIndexes:(MCOIndexSet *)indexes;
+// Returns an operation that will delete the given messages.
+// Will disconnect when finished.
+//
+// {
+//   ...
+//   MCOIndexSet * indexes = [MCOIndexSet indexSet];
+//   [indexes addIndex:1];
+//   [indexes addIndex:2];
+//   [indexes addIndex:3];
+//   MCOPOPOperation * op [session deleteMessagesOperationWithIndexes:indexes];
+//   [op start:^(NSError *error) {
+//        ...
+//   }]];
+//
+- (MCOPOPOperation *) deleteMessagesOperationWithIndexes:(MCOIndexSet *)indexes;
 
 @end
 
diff --git a/src/objc/pop/MCOPOPSession.mm b/src/objc/pop/MCOPOPSession.mm
index 1f468e99..b82c1f23 100644
--- a/src/objc/pop/MCOPOPSession.mm
+++ b/src/objc/pop/MCOPOPSession.mm
@@ -74,7 +74,7 @@ MCO_OBJC_SYNTHESIZE_BOOL(setCheckCertificateEnabled, isCheckCertificateEnabled)
 }
 
 // Will disconnect.
-- (MCOPOPOperation *) deleteMessagesWithIndexes:(MCOIndexSet *)indexes
+- (MCOPOPOperation *) deleteMessagesOperationWithIndexes:(MCOIndexSet *)indexes
 {
     mailcore::POPOperation * coreOp = MCO_NATIVE_INSTANCE->deleteMessagesOperation(MCO_FROM_OBJC(mailcore::IndexSet, indexes));
      return [[[MCOPOPOperation alloc] initWithMCOperation:coreOp] autorelease];