Work in progress on IMAP documentation.

45 files changed, 506 insertions, 68 deletions

diff --git a/build-mac/mailcore2.xcodeproj/project.pbxproj b/build-mac/mailcore2.xcodeproj/project.pbxproj
index 1b131e71..303e25e5 100644
--- a/build-mac/mailcore2.xcodeproj/project.pbxproj
+++ b/build-mac/mailcore2.xcodeproj/project.pbxproj
@@ -1830,10 +1830,6 @@
 				C64BB25416FD32A0000DB34C /* MCOIMAP.h */,
 				F8EA941416BAED6E0011AC6F /* MCOIMAPSession.h */,
 				C07AD057D3C8FBDC7AC95733 /* MCOIMAPSession.mm */,
-				F87F190816BB62690012652F /* MCOIMAPFetchFoldersOperation.h */,
-				F87F190B16BB62B00012652F /* MCOIMAPFetchFoldersOperation.mm */,
-				C623C58D16FE6B45001BBEFC /* MCOIMAPOperation.h */,
-				C623C58E16FE6B45001BBEFC /* MCOIMAPOperation.mm */,
 				C623C59116FE750D001BBEFC /* MCOIMAPFolder.h */,
 				C623C59216FE750E001BBEFC /* MCOIMAPFolder.mm */,
 				C6F5B9E016FEA1E800D9DABD /* MCOIMAPMessage.h */,
@@ -1848,10 +1844,14 @@
 				C6F5B9ED16FEA3C400D9DABD /* MCOIMAPNamespaceItem.mm */,
 				C6F5B9EF16FEA3D700D9DABD /* MCOIMAPPart.h */,
 				C6F5B9F016FEA3D700D9DABD /* MCOIMAPPart.mm */,
-				C6F61F79170169EE0073032E /* MCOIMAPFolderInfoOperation.h */,
-				C6F61F7A170169EE0073032E /* MCOIMAPFolderInfoOperation.mm */,
 				C6F61F9D17016EA00073032E /* MCOIMAPFolderInfo.h */,
 				C6F61F9E17016EA00073032E /* MCOIMAPFolderInfo.m */,
+				F87F190816BB62690012652F /* MCOIMAPFetchFoldersOperation.h */,
+				F87F190B16BB62B00012652F /* MCOIMAPFetchFoldersOperation.mm */,
+				C623C58D16FE6B45001BBEFC /* MCOIMAPOperation.h */,
+				C623C58E16FE6B45001BBEFC /* MCOIMAPOperation.mm */,
+				C6F61F79170169EE0073032E /* MCOIMAPFolderInfoOperation.h */,
+				C6F61F7A170169EE0073032E /* MCOIMAPFolderInfoOperation.mm */,
 				C6F61FB31702AB2A0073032E /* MCOIMAPBaseOperation.h */,
 				C6F61FB41702AB2F0073032E /* MCOIMAPBaseOperation.mm */,
 				C6F61F7C170169FB0073032E /* MCOIMAPAppendMessageOperation.h */,
diff --git a/src/async/imap/MCIMAPFetchMessagesOperation.cc b/src/async/imap/MCIMAPFetchMessagesOperation.cc
index 9432a1e0..ece60c66 100644
--- a/src/async/imap/MCIMAPFetchMessagesOperation.cc
+++ b/src/async/imap/MCIMAPFetchMessagesOperation.cc
@@ -17,12 +17,6 @@ using namespace mailcore;
 IMAPFetchMessagesOperation::IMAPFetchMessagesOperation()
 {
     mFetchByUidEnabled = false;
-#if 0
-    mFirst = 0;
-    mLast = 0;
-    mUids = NULL;
-    mNumbers = NULL;
-#endif
     mIndexes = NULL;
     mMessages = NULL;
     mVanishedMessages = NULL;
@@ -31,10 +25,6 @@ IMAPFetchMessagesOperation::IMAPFetchMessagesOperation()
 
 IMAPFetchMessagesOperation::~IMAPFetchMessagesOperation()
 {
-#if 0
-    MC_SAFE_RELEASE(mNumbers);
-    MC_SAFE_RELEASE(mUids);
-#endif
     MC_SAFE_RELEASE(mIndexes);
     MC_SAFE_RELEASE(mMessages);
     MC_SAFE_RELEASE(mVanishedMessages);
diff --git a/src/core/abstract/MCMessageConstants.h b/src/core/abstract/MCMessageConstants.h
index ee4e3197..c06acd06 100644
--- a/src/core/abstract/MCMessageConstants.h
+++ b/src/core/abstract/MCMessageConstants.h
@@ -108,7 +108,7 @@ namespace mailcore {
 		IMAPCapabilityXList,
 		IMAPCapabilityAuthAnonymous,
 		IMAPCapabilityAuthCRAMMD5,
-		MAPCapabilityAuthDigestMD5,
+		IMAPCapabilityAuthDigestMD5,
 		IMAPCapabilityAuthExternal,
 		IMAPCapabilityAuthGSSAPI,
 		IMAPCapabilityAuthKerberosV4,
diff --git a/src/core/imap/MCIMAPSession.cc b/src/core/imap/MCIMAPSession.cc
index 2b94b514..a3415468 100644
--- a/src/core/imap/MCIMAPSession.cc
+++ b/src/core/imap/MCIMAPSession.cc
@@ -1236,7 +1236,7 @@ void IMAPSession::copyMessages(String * folder, IndexSet * uidSet, String * dest
     }
 
     setList = splitSet(set, 10);
-    uidSetResult = IndexSet::indexSet();
+    uidSetResult = NULL;
 
     for(clistiter * iter = clist_begin(setList) ; iter != NULL ; iter = clist_next(iter)) {
         struct mailimap_set * current_set;
@@ -1267,7 +1267,7 @@ void IMAPSession::copyMessages(String * folder, IndexSet * uidSet, String * dest
             mailimap_set_free(dest_uid);
         }
     }
-    * pDestUIDs = (IndexSet *) uidSetResult->autorelease();
+    * pDestUIDs = uidSetResult;
     * pError = ErrorNone;
 
     release:
diff --git a/src/objc/abstract/MCOAbstractPart.h b/src/objc/abstract/MCOAbstractPart.h
index 432863bf..6fb14fcd 100644
--- a/src/objc/abstract/MCOAbstractPart.h
+++ b/src/objc/abstract/MCOAbstractPart.h
@@ -15,10 +15,24 @@
 @class MCOAbstractMessage;
 
 typedef enum {
+    // Used for a single part.
+    // The part will be a MCOAbstractPart.
     MCOPartTypeSingle,
+    
+    // Used for a message part (MIME type: message/rfc822).
+    // The part will be a MCOAbstractMessagePart.
     MCOPartTypeMessage,
+    
+    // Used for a multipart, multipart/mixed.
+    // The part will be a MCOAbstractMultipart.
     MCOPartTypeMultipartMixed,
+    
+    // Used for a multipart, multipart/related.
+    // The part will be a MCOAbstractMultipart.
     MCOPartTypeMultipartRelated,
+    
+    // Used for a multipart, multipart/alternative.
+    // The part will be a MCOAbstractMultipart.
     MCOPartTypeMultipartAlternative,
 } MCOPartType;
 
diff --git a/src/objc/abstract/MCOConstants.h b/src/objc/abstract/MCOConstants.h
index e014795d..a8cf7bd4 100644
--- a/src/objc/abstract/MCOConstants.h
+++ b/src/objc/abstract/MCOConstants.h
@@ -166,6 +166,85 @@ typedef enum {
     MCOIMAPSearchKindAnd,
 } MCOIMAPSearchKind;
 
+// Keys for the namespace dictionary.
+#define MCOIMAPNamespacePersonal @"IMAPNamespacePersonal";
+#define MCOIMAPNamespaceOther @"IMAPNamespaceOther";
+#define MCOIMAPNamespaceShared @"IMAPNamespaceShared";
+
+// This is the constants for the IMAP capabilities.
+// See corresponding RFC for more information.
+typedef enum {
+    // ACL Capability.
+    MCOIMAPCapabilityACL,
+    // BINARY Capability.
+    MCOIMAPCapabilityBinary,
+    // CATENATE Capability.
+    MCOIMAPCapabilityCatenate,
+    // CHILDREN Capability.
+    MCOIMAPCapabilityChildren,
+    // COMPRESS Capability.
+    MCOIMAPCapabilityCompressDeflate,
+    // CONDSTORE Capability.
+    MCOIMAPCapabilityCondstore,
+    // ENABLE Capability.
+    MCOIMAPCapabilityEnable,
+    // IDLE Capability.
+    MCOIMAPCapabilityIdle,
+    // ID Capability.
+    MCOIMAPCapabilityId,
+    // LITERAL+ Capability.
+    MCOIMAPCapabilityLiteralPlus,
+    // MULTIAPPEND Capability.
+    MCOIMAPCapabilityMultiAppend,
+    // NAMESPACE Capability.
+    MCOIMAPCapabilityNamespace,
+    // QRESYNC Capability.
+    MCOIMAPCapabilityQResync,
+    // QUOTE Capability.
+    MCOIMAPCapabilityQuota,
+    // SORT Capability.
+    MCOIMAPCapabilitySort,
+    // STARTTLS Capability.
+    MCOIMAPCapabilityStartTLS,
+    // THREAD=ORDEREDSUBJECT Capability.
+    MCOIMAPCapabilityThreadOrderedSubject,
+    // THREAD=REFERENCES Capability.
+    MCOIMAPCapabilityThreadReferences,
+    // UIDPLUS Capability.
+    MCOIMAPCapabilityUIDPlus,
+    // UNSELECT Capability.
+    MCOIMAPCapabilityUnselect,
+    // XLIST Capability.
+    MCOIMAPCapabilityXList,
+    // AUTH=ANONYMOUS Capability.
+    MCOIMAPCapabilityAuthAnonymous,
+    // AUTH=CRAM-MD5 Capability.
+    MCOIMAPCapabilityAuthCRAMMD5,
+    // AUTH=DIGEST-MD5 Capability.
+    MCOIMAPCapabilityAuthDigestMD5,
+    // AUTH=EXTERNAL Capability.
+    MCOIMAPCapabilityAuthExternal,
+    // AUTH=GSSAPI Capability.
+    MCOIMAPCapabilityAuthGSSAPI,
+    // AUTH=KERBEROSV4 Capability.
+    MCOIMAPCapabilityAuthKerberosV4,
+    // AUTH=LOGIN Capability.
+    MCOIMAPCapabilityAuthLogin,
+    // AUTH=NTML Capability.
+    MCOIMAPCapabilityAuthNTLM,
+    // AUTH=OTP Capability.
+    MCOIMAPCapabilityAuthOTP,
+    // AUTH=PLAIN Capability.
+    MCOIMAPCapabilityAuthPlain,
+    // AUTH=SKEY Capability.
+    MCOIMAPCapabilityAuthSKey,
+    // AUTH=SRP Capability.
+    MCOIMAPCapabilityAuthSRP,
+} MCOIMAPCapability;
+
+// Error domain for mailcore.
+#define MCOErrorDomain @"MCOErrorDomain"
+
 // Here's the list of errors.
 typedef enum {
     // No error occurred.
diff --git a/src/objc/imap/MCOIMAPAppendMessageOperation.h b/src/objc/imap/MCOIMAPAppendMessageOperation.h
index 0377d797..95f29f5d 100644
--- a/src/objc/imap/MCOIMAPAppendMessageOperation.h
+++ b/src/objc/imap/MCOIMAPAppendMessageOperation.h
@@ -10,14 +10,23 @@
 
 #define __MAILCORE_MCOIMAPAPPENDMESSAGEOPERATION_H_
 
+// This class implements an operation that adds a message to a folder.
+
 #import <MailCore/MCOIMAPBaseOperation.h>
 #import <MailCore/MCOConstants.h>
 
 @interface MCOIMAPAppendMessageOperation : MCOIMAPBaseOperation
 
+// This block will be called during the progression while sending the message
+// when some bytes have been sent to the network.
 @property (nonatomic, copy) MCOIMAPBaseOperationProgressBlock progress;
 
-- (void)start:(void (^)(NSError *error, uint32_t createdUID))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error. createdUID will be the value of the UID of
+// the created message is the server supports UIDPLUS or zero if not.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// createdUID will be zero.
+- (void) start:(void (^)(NSError * error, uint32_t createdUID))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPBaseOperation.h b/src/objc/imap/MCOIMAPBaseOperation.h
index 226f0ed7..84e03892 100644
--- a/src/objc/imap/MCOIMAPBaseOperation.h
+++ b/src/objc/imap/MCOIMAPBaseOperation.h
@@ -10,6 +10,8 @@
 
 #define __MAILCORE_MCOIMAPBASEOPERATION_H_
 
+// It's a generic IMAP operation with progress.
+
 #import <MailCore/MCOOperation.h>
 
 typedef void (^MCOIMAPBaseOperationProgressBlock)(unsigned int current, unsigned int maximum);
@@ -17,8 +19,12 @@ typedef void (^MCOIMAPBaseOperationItemProgressBlock)(unsigned int current);
 
 @interface MCOIMAPBaseOperation : MCOOperation
 
-// to be overriden by subclasses.
+// those two methods can be overriden by subclasses.
+
+// It will be called when a send or receive of a content of a message will occur.
 - (void) bodyProgress:(unsigned int)current maximum:(unsigned int)maximum;
+
+// It will be called when a new item is received in a list of items.
 - (void) itemProgress:(unsigned int)current maximum:(unsigned int)maximum;
 
 @end
diff --git a/src/objc/imap/MCOIMAPCapabilityOperation.h b/src/objc/imap/MCOIMAPCapabilityOperation.h
index f1e662a8..38166e0b 100644
--- a/src/objc/imap/MCOIMAPCapabilityOperation.h
+++ b/src/objc/imap/MCOIMAPCapabilityOperation.h
@@ -10,13 +10,20 @@
 
 #define __MAILCORE_MCOIMAPCAPBILITYOPERATION_H_
 
+// This class implements an operation to query capabilities.
+
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @class MCOIndexSet;
 
 @interface MCOIMAPCapabilityOperation : MCOIMAPBaseOperation
 
-- (void)start:(void (^)(NSError *error, MCOIndexSet * capabilities))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error. capabilities is a set of IMAP capabilities.
+// See MCOConstants.h / MCOIMAPCapability.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// info will be nil.
+- (void) start:(void (^)(NSError * error, MCOIndexSet * capabilities))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPCopyMessagesOperation.h b/src/objc/imap/MCOIMAPCopyMessagesOperation.h
index 112d23fa..0fb3c5ad 100644
--- a/src/objc/imap/MCOIMAPCopyMessagesOperation.h
+++ b/src/objc/imap/MCOIMAPCopyMessagesOperation.h
@@ -12,11 +12,18 @@
 
 #define __MAILCORE_MCOCOPYMESSAGESOPERATION_H_
 
+// This class implements an operation to copy messages.
+
 @class MCOIndexSet;
 
 @interface MCOIMAPCopyMessagesOperation : MCOIMAPBaseOperation
 
-- (void)start:(void (^)(NSError *error, MCOIndexSet * destUids))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error. destUids will contain the UID of the messages
+// created in the destination folder if UIDPLUS is supported. destUids will be nil if UIDPLUS is not supported.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// info will be nil.
+- (void) start:(void (^)(NSError * error, MCOIndexSet * destUids))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPFetchContentOperation.h b/src/objc/imap/MCOIMAPFetchContentOperation.h
index e1869d66..f43425bb 100644
--- a/src/objc/imap/MCOIMAPFetchContentOperation.h
+++ b/src/objc/imap/MCOIMAPFetchContentOperation.h
@@ -10,14 +10,23 @@
 
 #define __MAILCORE_MCOIMAPFETCHCONTENTOPERATION_H_
 
+// This class implements an operation to fetch the content of a message.
+// It can be a part or a full message.
+
 #import <MailCore/MCOIMAPBaseOperation.h>
 #import <MailCore/MCOConstants.h>
 
 @interface MCOIMAPFetchContentOperation : MCOIMAPBaseOperation
 
+// This block will be called during the progression while receiving the message
+// when some bytes have been downloaded from the network.
 @property (nonatomic, copy) MCOIMAPBaseOperationProgressBlock progress;
 
-- (void)start:(void (^)(NSError *error, NSData * data))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error. data contains the requested data of the message.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// data will be nil.
+- (void) start:(void (^)(NSError * error, NSData * data))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPFetchFoldersOperation.h b/src/objc/imap/MCOIMAPFetchFoldersOperation.h
index 87912f60..90feb870 100644
--- a/src/objc/imap/MCOIMAPFetchFoldersOperation.h
+++ b/src/objc/imap/MCOIMAPFetchFoldersOperation.h
@@ -10,10 +10,18 @@
 
 #define __MAILCORE_MCOIMAPFETCHFOLDERSOPERATION_H_
 
+// This class implements an operation to fetch a list of folders.
+
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @interface MCOIMAPFetchFoldersOperation : MCOIMAPBaseOperation
-- (void)start:(void (^)(NSError *error, NSArray *folder))completionBlock;
+
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error. folders will be an array of MCOIMAPFolder.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// folders will be nil.
+- (void) start:(void (^)(NSError * error, NSArray * /* MCOIMAPFolder */ folders))completionBlock;
+
 @end
 
 #endif
diff --git a/src/objc/imap/MCOIMAPFetchFoldersOperation.mm b/src/objc/imap/MCOIMAPFetchFoldersOperation.mm
index 4700ee85..53017c90 100644
--- a/src/objc/imap/MCOIMAPFetchFoldersOperation.mm
+++ b/src/objc/imap/MCOIMAPFetchFoldersOperation.mm
@@ -43,7 +43,7 @@ typedef void (^CompletionType)(NSError *error, NSArray *folder);
     [super dealloc];
 }
 
-- (void)start:(void (^)(NSError *error, NSArray *folder))completionBlock {
+- (void)start:(void (^)(NSError *error, NSArray * /* MCOIMAPFolder */ folders))completionBlock {
     _completionBlock = [completionBlock copy];
     [self start];
 }
diff --git a/src/objc/imap/MCOIMAPFetchMessagesOperation.h b/src/objc/imap/MCOIMAPFetchMessagesOperation.h
index adde2dbd..32a3a451 100644
--- a/src/objc/imap/MCOIMAPFetchMessagesOperation.h
+++ b/src/objc/imap/MCOIMAPFetchMessagesOperation.h
@@ -13,13 +13,22 @@
 #import <MailCore/MCOIMAPBaseOperation.h>
 #import <MailCore/MCOConstants.h>
 
+// This class implements an operation to fetch a list of messages.
+
 @class MCOIndexSet;
 
 @interface MCOIMAPFetchMessagesOperation : MCOIMAPBaseOperation
 
+// This block will be called each time a new message information will be downloaded.
 @property (nonatomic, copy) MCOIMAPBaseOperationItemProgressBlock progress;
 
-- (void)start:(void (^)(NSError *error, NSArray * messages, MCOIndexSet * vanishedMessages))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error. messages will be an array of MCOIMAPMessage.
+// vanishedMessages will contain the messages removed on the server if the server supports QRESYNC and if it was a sync request.
+// In other case, vanishedMessages will be nil.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// messages and vanishedMessages will be nil.
+- (void) start:(void (^)(NSError * error, NSArray * /* MCOIMAPMessage */ messages, MCOIndexSet * vanishedMessages))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPFetchNamespaceOperation.h b/src/objc/imap/MCOIMAPFetchNamespaceOperation.h
index 90702e85..b7e5fb64 100644
--- a/src/objc/imap/MCOIMAPFetchNamespaceOperation.h
+++ b/src/objc/imap/MCOIMAPFetchNamespaceOperation.h
@@ -10,11 +10,24 @@
 
 #define __MAILCORE_MCOIMAPFETCHNAMESPACEOPERATION_H_
 
+// This class implements an operation to fetch namespaces.
+
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @interface MCOIMAPFetchNamespaceOperation : MCOIMAPBaseOperation
 
-- (void)start:(void (^)(NSError *error, NSDictionary * namespaces))completionBlock;
+// Starts the asynchronous operation.
+//
+// On success, the completion block will be called with nil as error.
+// namespaces is a dictionary with the following keys:
+// MCOIMAPNamespacePersonal for personal namespaces,
+// MCOIMAPNamespaceOther for other namespaces,
+// MCOIMAPNamespaceShared for shared namespaces.
+// Values are MCOIMAPNamespace.
+//
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// namespaces will be nil.
+- (void) start:(void (^)(NSError * error, NSDictionary * namespaces))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPFolder.h b/src/objc/imap/MCOIMAPFolder.h
index 813303e2..03858fc5 100644
--- a/src/objc/imap/MCOIMAPFolder.h
+++ b/src/objc/imap/MCOIMAPFolder.h
@@ -10,13 +10,20 @@
 
 #define __MAILCORE_MCOIMAPFOLDER_H_
 
+// This class implements an IMAP folder.
+
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOConstants.h>
 
 @interface MCOIMAPFolder : NSObject <NSCopying>
 
+// It's the path of the folder.
 @property (nonatomic, copy) NSString * path;
+
+// It's the delimiter for each component of the path.
 @property (nonatomic, assign) char delimiter;
+
+// It's the flags of the folder. See MCOIMAPFolderFlag.
 @property (nonatomic, assign) MCOIMAPFolderFlag flags;
 
 @end
diff --git a/src/objc/imap/MCOIMAPFolderInfo.h b/src/objc/imap/MCOIMAPFolderInfo.h
index 8b058deb..cbeb64f2 100644
--- a/src/objc/imap/MCOIMAPFolderInfo.h
+++ b/src/objc/imap/MCOIMAPFolderInfo.h
@@ -12,13 +12,23 @@
 
 #import <Foundation/Foundation.h>
 
+// This class is a cluster for some folder information.
+
 @interface MCOIMAPFolderInfo : NSObject
 
+// Returns a new allocated folder info.
 + (MCOIMAPFolderInfo *) info;
 
+// UIDNEXT value.
 @property (nonatomic, assign) uint32_t uidNext;
+
+// UIDVALIDITY value.
 @property (nonatomic, assign) uint32_t uidValidity;
+
+// MODSEQ value.
 @property (nonatomic, assign) uint64_t modSequenceValue;
+
+// number of messages.
 @property (nonatomic, assign) int messageCount;
 
 @end
diff --git a/src/objc/imap/MCOIMAPFolderInfoOperation.h b/src/objc/imap/MCOIMAPFolderInfoOperation.h
index feb9ea39..d05da566 100644
--- a/src/objc/imap/MCOIMAPFolderInfoOperation.h
+++ b/src/objc/imap/MCOIMAPFolderInfoOperation.h
@@ -12,10 +12,19 @@
 
 #import <MailCore/MCOIMAPBaseOperation.h>
 
+// This class implements the operation that will fetch some folder information
+// (uidNext uidValidity, modSequenceValue, messageCount).
+
 @class MCOIMAPFolderInfo;
 
 @interface MCOIMAPFolderInfoOperation : MCOIMAPBaseOperation
-- (void)start:(void (^)(NSError *error, MCOIMAPFolderInfo *info))completionBlock;
+
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error. info contains the folder information.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// info will be nil.
+- (void) start:(void (^)(NSError * error, MCOIMAPFolderInfo *info))completionBlock;
+
 @end
 
 #endif
diff --git a/src/objc/imap/MCOIMAPIdentityOperation.h b/src/objc/imap/MCOIMAPIdentityOperation.h
index 60d040e3..0a32892c 100644
--- a/src/objc/imap/MCOIMAPIdentityOperation.h
+++ b/src/objc/imap/MCOIMAPIdentityOperation.h
@@ -10,11 +10,18 @@
 
 #define __MAILCORE_MCOIMAPIDENTITYOPERATION_H_
 
+// This class implements an operation to get/send identity.
+
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @interface MCOIMAPIdentityOperation : MCOIMAPBaseOperation
 
-- (void)start:(void (^)(NSError *error, NSDictionary * serverIdentity))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error. serverIdentity contains the server identity information.
+// See RFC 2971 for the common keys of this dictionary.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// serverIdentity will be nil.
+- (void) start:(void (^)(NSError * error, NSDictionary * serverIdentity))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPIdleOperation.h b/src/objc/imap/MCOIMAPIdleOperation.h
index 365457d9..2da19d19 100644
--- a/src/objc/imap/MCOIMAPIdleOperation.h
+++ b/src/objc/imap/MCOIMAPIdleOperation.h
@@ -10,13 +10,19 @@
 
 #define __MAILCORE_MCOIMAPIDLEOPERATION_H_
 
+// This class implements an idle operation.
+
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @interface MCOIMAPIdleOperation : MCOIMAPBaseOperation
 
+// Interrupts the IDLE operation.
 - (void) interruptIdle;
 
-- (void)start:(void (^)(NSError *error))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+- (void) start:(void (^)(NSError * error))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPMessage.h b/src/objc/imap/MCOIMAPMessage.h
index c6196103..bcc1b5a1 100644
--- a/src/objc/imap/MCOIMAPMessage.h
+++ b/src/objc/imap/MCOIMAPMessage.h
@@ -10,6 +10,8 @@
 
 #define __MAILCORE_MCOIMAPMESSAGE_H_
 
+// This class implements an IMAP message.
+
 #import <MailCore/MCOAbstractMessage.h>
 #import <MailCore/MCOConstants.h>
 
@@ -17,17 +19,32 @@
 
 @interface MCOIMAPMessage : MCOAbstractMessage <NSCopying>
 
+// It's the UID of the message.
 @property (nonatomic, assign) uint32_t uid;
+
+// It's the flags of the message.
 @property (nonatomic, assign) MCOMessageFlag flags;
+
+// It's the flags of the message fetched from the server.
 @property (nonatomic, assign) MCOMessageFlag originalFlags;
+
+// It's the last modification sequence value of the message synced from the server.
 @property (nonatomic, assign) uint64_t modSeqValue;
+
+// It's the main MIME part of the message.
 @property (nonatomic, retain) MCOAbstractPart * mainPart;
+
+// It's the Gmail labels of the message.
 @property (nonatomic, copy) NSArray * gmailLabels;
 
+// Returns the part with the given part identifier.
+// A part identifier looks like 1.2.1
 - (MCOAbstractPart *) partForPartID:(NSString *)partID;
-- (MCOAbstractPart *) partForContentID:(NSString *)contentID;
-- (MCOAbstractPart *) partForUniqueID:(NSString *)uniqueID;
 
+// HTML rendering of the message to be displayed in a web view.
+// The delegate should implement at least
+// -MCOAbstractMessage:dataForIMAPPart:folder:
+// so that the complete HTML rendering can have a chance to take place.
 - (NSString *) htmlRenderingWithFolder:(NSString *)folder
                               delegate:(id <MCOHTMLRendererIMAPDelegate>)delegate;
 
diff --git a/src/objc/imap/MCOIMAPMessage.mm b/src/objc/imap/MCOIMAPMessage.mm
index 808f8deb..9984443e 100644
--- a/src/objc/imap/MCOIMAPMessage.mm
+++ b/src/objc/imap/MCOIMAPMessage.mm
@@ -53,16 +53,6 @@ MCO_OBJC_SYNTHESIZE_ARRAY(setGmailLabels, gmailLabels)
     return MCO_TO_OBJC(MCO_NATIVE_INSTANCE->partForPartID([partID mco_mcString]));
 }
 
-- (MCOAbstractPart *) partForContentID:(NSString *)contentID
-{
-    return MCO_TO_OBJC(MCO_NATIVE_INSTANCE->partForContentID([contentID mco_mcString]));
-}
-
-- (MCOAbstractPart *) partForUniqueID:(NSString *)uniqueID
-{
-    return MCO_TO_OBJC(MCO_NATIVE_INSTANCE->partForUniqueID([uniqueID mco_mcString]));
-}
-
 - (NSString *) htmlRenderingWithFolder:(NSString *)folder
                               delegate:(id <MCOHTMLRendererIMAPDelegate>)delegate
 {
diff --git a/src/objc/imap/MCOIMAPMessagePart.h b/src/objc/imap/MCOIMAPMessagePart.h
index bda7d5be..22ce8a50 100644
--- a/src/objc/imap/MCOIMAPMessagePart.h
+++ b/src/objc/imap/MCOIMAPMessagePart.h
@@ -10,10 +10,14 @@
 
 #define __MAILCORE_MCOIMAPMESSAGEPART_H_
 
+// This class implements a message part.
+
 #import <MailCore/MCOAbstractMessagePart.h>
 
 @interface MCOIMAPMessagePart : MCOAbstractMessagePart <NSCopying>
 
+// It's the part identifier.
+// A part identifier looks like 1.2.1
 @property (nonatomic, copy) NSString * partID;
 
 @end
diff --git a/src/objc/imap/MCOIMAPMultipart.h b/src/objc/imap/MCOIMAPMultipart.h
index 950be8de..d178a2ce 100644
--- a/src/objc/imap/MCOIMAPMultipart.h
+++ b/src/objc/imap/MCOIMAPMultipart.h
@@ -10,10 +10,14 @@
 
 #define __MAILCORE_MCOIMAPMULTIPART_H_
 
+// This class implements a multipart.
+
 #import <MailCore/MCOAbstractMultipart.h>
 
 @interface MCOIMAPMultipart : MCOAbstractMultipart <NSCopying>
 
+// It's the part identifier.
+// A part identifier looks like 1.2.1
 @property (nonatomic, copy) NSString * partID;
 
 @end
diff --git a/src/objc/imap/MCOIMAPNamespace.h b/src/objc/imap/MCOIMAPNamespace.h
index b1dc15a0..392a3d1b 100644
--- a/src/objc/imap/MCOIMAPNamespace.h
+++ b/src/objc/imap/MCOIMAPNamespace.h
@@ -10,20 +10,39 @@
 
 #define __MAILCORE_MCOIMAPNAMESPACE_H_
 
+// This class implements an IMAP namespace.
+
 #import <Foundation/Foundation.h>
 
 @class MCOIMAPNamespace;
 
 @interface MCOIMAPNamespace : NSObject <NSCopying>
 
+// Returns a simple namespace with only an item.
+// This item will have the given prefix and the given path delimiter.
 + (MCOIMAPNamespace *) namespaceWithPrefix:(NSString *)prefix delimiter:(char)delimiter;
 
+// Returns the prefix of the main item of this namespace.
 - (NSString *) mainPrefix;
+
+// Returns the path delimiter of the main item of this namespace.
 - (char) mainDelimiter;
+
+// Returns the list of prefixes of this namespace.
 - (NSArray *) prefixes;
+
+// Returns the folder path for the given list of path components in the context
+// of the main item of the namespace.
 - (NSString *) pathForComponents:(NSArray *)components;
+
+// Returns the folder path for the given list of path components and a prefix.
+// It will use the best item matching the prefix to compute the path.
 - (NSString *) pathForComponents:(NSArray *)components prefix:(NSString *)prefix;
+
+// Returns the components given a folder path.
 - (NSArray *) componentsFromPath:(NSString *)path;
+
+// Returns YES if the namespace contains the given folder path.
 - (BOOL) containsFolderPath:(NSString *)path;
 
 @end
diff --git a/src/objc/imap/MCOIMAPNamespaceItem.h b/src/objc/imap/MCOIMAPNamespaceItem.h
index 376434ff..6171b464 100644
--- a/src/objc/imap/MCOIMAPNamespaceItem.h
+++ b/src/objc/imap/MCOIMAPNamespaceItem.h
@@ -10,15 +10,25 @@
 
 #define __MAILCORE_MCOIMAPNAMESPACEITEM_H_
 
+// This class implements an IMAP namespace item.
+
 #import <Foundation/Foundation.h>
 
 @interface MCOIMAPNamespaceItem : NSObject <NSCopying>
 
+// This is the prefix for this namespace item.
 @property (nonatomic, copy) NSString * prefix;
+
+// This is the delimiter of the path for this namespace item.
 @property (nonatomic, assign) char delimiter;
 
+// Returns folder path for given path components in the context of this namespace item.
 - (NSString *) pathForComponents:(NSArray *)components;
+
+// Returns components for the given path in the context of this namespace item.
 - (NSArray *) componentsForPath:(NSString *)path;
+
+// Returns YES if the namespace contains this folder path.
 - (BOOL) containsFolder:(NSString *)folder;
 
 @end
diff --git a/src/objc/imap/MCOIMAPOperation.h b/src/objc/imap/MCOIMAPOperation.h
index 1954f00b..74aba70a 100644
--- a/src/objc/imap/MCOIMAPOperation.h
+++ b/src/objc/imap/MCOIMAPOperation.h
@@ -10,11 +10,16 @@
 
 #define __MAILCORE_MCOIMAPOPERATION_H_
 
+// This class implements a generic IMAP operation.
+
 #import <MailCore/MCOOperation.h>
 
 @interface MCOIMAPOperation : MCOOperation
 
-- (void)start:(void (^)(NSError *error))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+- (void) start:(void (^)(NSError * error))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPPart.h b/src/objc/imap/MCOIMAPPart.h
index 588abe10..58bdfd2d 100644
--- a/src/objc/imap/MCOIMAPPart.h
+++ b/src/objc/imap/MCOIMAPPart.h
@@ -16,10 +16,18 @@
 
 @interface MCOIMAPPart : MCOAbstractPart <NSCopying>
 
+// It's the part identifier.
+// A part identifier looks like 1.2.1
 @property (nonatomic, copy) NSString * partID;
+
+// It's the size of the single part.
 @property (nonatomic, nonatomic) unsigned int size;
+
+// It's the encoding of the single part.
 @property (nonatomic, nonatomic) MCOEncoding encoding;
 
+// Returns the decoded size of the part.
+// For example, for a part that's encoded with base64, it will return actual_size * 3/4.
 - (unsigned int) decodedSize;
 
 @end
diff --git a/src/objc/imap/MCOIMAPSearchExpression.h b/src/objc/imap/MCOIMAPSearchExpression.h
index 36020d7c..d0c439e9 100644
--- a/src/objc/imap/MCOIMAPSearchExpression.h
+++ b/src/objc/imap/MCOIMAPSearchExpression.h
@@ -10,17 +10,64 @@
 
 #define __MAILCORE_MCOIMAPSEARCHEXPRESSION_H_
 
+// This class implements a search expression.
+
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOConstants.h>
 
 @interface MCOIMAPSearchExpression : NSObject
 
+// Creates a search expression that matches the sender of an email.
+//
+// Example:
+// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"]
+//
 + (MCOIMAPSearchExpression *) searchFrom:(NSString *)value;
+
+// Creates a search expression that matches any recipient of an email.
+//
+// Example:
+// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchRecipient:@"ngan@etpan.org"]
+//
 + (MCOIMAPSearchExpression *) searchRecipient:(NSString *)value;
+
+// Creates a search expression that matches the subject of an email.
+//
+// Example:
+// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchSubject:@"airline"]
+//
 + (MCOIMAPSearchExpression *) searchSubject:(NSString *)value;
+
+// Creates a search expression that matches the content of an email.
+//
+// Example:
+// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchContent:@"meeting"]
+//
 + (MCOIMAPSearchExpression *) searchContent:(NSString *)value;
+
+// Creates a search expression that matches the content of a specific header.
+//
+// Example:
+// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchHeader:@"List-Id" value:@"shoes"]
+//
 + (MCOIMAPSearchExpression *) searchHeader:(NSString *)header value:(NSString *)value;
+
+// Creates a search expression that's a disjunction of two search expressions.
+//
+// Example:
+// MCOIMAPSearchExpression * exprFrom = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"]
+// MCOIMAPSearchExpression * exprSubject = [MCOIMAPSearchExpression searchContent:@"meeting"]
+// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchAnd:exprFrom other:exprSubject];
+//
 + (MCOIMAPSearchExpression *) searchAnd:(MCOIMAPSearchExpression *)expression other:(MCOIMAPSearchExpression *)other;
+
+// Creates a search expression that's a conjunction of two search expressions.
+//
+// Example:
+// MCOIMAPSearchExpression * exprFrom = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"]
+// MCOIMAPSearchExpression * exprOtherFrom = [MCOIMAPSearchExpression searchRecipient:@"ngan@etpan.org"]
+// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchOr:exprFrom exprOtherFrom];
+//
 + (MCOIMAPSearchExpression *) searchOr:(MCOIMAPSearchExpression *)expression other:(MCOIMAPSearchExpression *)other;
 
 @end
diff --git a/src/objc/imap/MCOIMAPSearchOperation.h b/src/objc/imap/MCOIMAPSearchOperation.h
index 79d1c26d..25795cfb 100644
--- a/src/objc/imap/MCOIMAPSearchOperation.h
+++ b/src/objc/imap/MCOIMAPSearchOperation.h
@@ -10,13 +10,19 @@
 
 #define __MAILCORE_MCOSEARCHOPERATION_H_
 
+// This class implements a search operation.
+
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @class MCOIndexSet;
 
 @interface MCOIMAPSearchOperation : MCOIMAPBaseOperation
 
-- (void)start:(void (^)(NSError *error, MCOIndexSet * searchResult))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error. searchResult will contain the UID of the messages.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// searchResult will be nil.
+- (void) start:(void (^)(NSError * error, MCOIndexSet * searchResult))completionBlock;
 
 @end
 
diff --git a/src/objc/imap/MCOIMAPSession.h b/src/objc/imap/MCOIMAPSession.h
index 0bb49177..03584762 100644
--- a/src/objc/imap/MCOIMAPSession.h
+++ b/src/objc/imap/MCOIMAPSession.h
@@ -29,105 +29,205 @@
 @class MCOIMAPIdentityOperation;
 @class MCOIMAPCapabilityOperation;
 
+// This class implements asynchronous IMAP protocol.
+
 @interface MCOIMAPSession : NSObject
 
+// This is the hostname of the POP3 server to connect to.
 @property (nonatomic, strong) NSString *hostname;
+
+// This is the port of the IMAP server to connect to.
 @property (nonatomic, assign) unsigned int port;
+
+// This is the username of the account.
 @property (nonatomic, strong) NSString *username;
+
+// This is the password of the account.
 @property (nonatomic, strong) 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) BOOL checkCertificateEnabled;
+
+// When set to YES, VoIP capability will be enabled on the IMAP connection on iOS.
 @property (nonatomic, assign, getter=isVoIPEnabled) BOOL VoIPEnabled;
+
+// The default delimiter for the folder paths.
 @property (nonatomic, assign) char delimiter;
 
+// The default namespace.
 @property (nonatomic, strong) MCOIMAPNamespace * defaultNamespace;
+
+// When set to YES, the session is allowed open to open several connections
+// to the same folder.
 @property (nonatomic, assign) BOOL allowsFolderConcurrentAccessEnabled;
-@property (nonatomic, assign) unsigned int maximumConnectons;
 
+// Maximum number of connections to the server allowed.
+@property (nonatomic, assign) unsigned int maximumConnections;
+
+// Returns a request operation for some info of the folder
+// The operation needs to be started.
+// (uidNext uidValidity, modSequenceValue, messageCount).
 - (MCOIMAPFolderInfoOperation *) folderInfoOperation:(NSString *)folder;
+
+// Returns an operation to fetch subscribed folders.
+// The operation needs to be started.
 - (MCOIMAPFetchFoldersOperation *) fetchSubscribedFoldersOperation;
+
+// Returns an operation to fetch all folders.
+// The operation needs to be started.
 - (MCOIMAPFetchFoldersOperation *) fetchAllFoldersOperation;
 
+// Returns an operation to rename a folder.
+// The operation needs to be started.
 - (MCOIMAPOperation *) renameFolderOperation:(NSString *)folder otherName:(NSString *)otherName;
+
+// Returns an operation to delete a folder.
+// The operation needs to be started.
 - (MCOIMAPOperation *) deleteFolderOperation:(NSString *)folder;
+
+// Returns an operation to create a folder.
+// The operation needs to be started.
 - (MCOIMAPOperation *) createFolderOperation:(NSString *)folder;
 
+// Returns an operation to subscribe a folder.
+// The operation needs to be started.
 - (MCOIMAPOperation *) subscribeFolderOperation:(NSString *)folder;
+
+// Returns an operation to unsubscribe a folder.
+// The operation needs to be started.
 - (MCOIMAPOperation *) unsubscribeFolderOperation:(NSString *)folder;
 
+// Returns an operation to add a message to a folder.
+// The operation needs to be started.
 - (MCOIMAPAppendMessageOperation *)appendMessageOperationWithFolder:(NSString *)folder
                                                         messageData:(NSData *)messageData
                                                               flags:(MCOMessageFlag)flags;
 
+// Returns an operation to copy messages to a folder.
+// The operation needs to be started.
 - (MCOIMAPCopyMessagesOperation *)copyMessagesOperationWithFolder:(NSString *)folder
                                                              uids:(MCOIndexSet *)uids
                                                        destFolder:(NSString *)destFolder;
 
 
+// Returns an operation to expunge a folder.
+// The operation needs to be started.
 - (MCOIMAPOperation *) expungeOperation:(NSString *)folder;
 
+// Returns an operation to fetch messages by UID.
+// The operation needs to be started.
 - (MCOIMAPFetchMessagesOperation *) fetchMessagesByUIDOperationWithFolder:(NSString *)folder
                                                               requestKind:(MCOIMAPMessagesRequestKind)requestKind
                                                                      uids:(MCOIndexSet *)uids;
 
+// Returns an operation to fetch messages by number.
+// The operation needs to be started.
 - (MCOIMAPFetchMessagesOperation *) fetchMessagesByNumberOperationWithFolder:(NSString *)folder
                                                                  requestKind:(MCOIMAPMessagesRequestKind)requestKind
                                                                      numbers:(MCOIndexSet *)numbers;
 
+// Returns an operation to sync the last changes related to the given message list given a modSeq.
+// The operation needs to be started.
 - (MCOIMAPFetchMessagesOperation *) syncMessagesByUIDWithFolder:(NSString *)folder
                                                     requestKind:(MCOIMAPMessagesRequestKind)requestKind
                                                            uids:(MCOIndexSet *)uids
                                                          modSeq:(uint64_t)modSeq;
 
+// Returns an operation to fetch the content of a message.
+// The operation needs to be started.
+// If urgent is set to YES, an additional connection to the same folder might be opened to fetch the content.
 - (MCOIMAPFetchContentOperation *) fetchMessageByUIDOperationWithFolder:(NSString *)folder
                                                                     uid:(uint32_t)uid
                                                                  urgent:(BOOL)urgent;
 
+// Returns an operation to fetch the content of a message.
+// The operation needs to be started.
 - (MCOIMAPFetchContentOperation *) fetchMessageByUIDOperationWithFolder:(NSString *)folder
                                                                     uid:(uint32_t)uid;
 
+// Returns an operation to fetch an attachment.
+// The operation needs to be started.
+// If urgent is set to YES, an additional connection to the same folder might be opened to fetch the content.
 - (MCOIMAPFetchContentOperation *) fetchMessageAttachmentByUIDOperationWithFolder:(NSString *)folder
                                                                               uid:(uint32_t)uid
                                                                            partID:(NSString *)partID
                                                                          encoding:(MCOEncoding)encoding
                                                                            urgent:(BOOL)urgent;
 
+// Returns an operation to fetch an attachment.
+// The operation needs to be started.
 - (MCOIMAPFetchContentOperation *) fetchMessageAttachmentByUIDOperationWithFolder:(NSString *)folder
                                                                               uid:(uint32_t)uid
                                                                            partID:(NSString *)partID
                                                                          encoding:(MCOEncoding)encoding;
 
+// Returns an operation to change flags of messages.
+// The operation needs to be started.
 - (MCOIMAPOperation *) storeFlagsOperationWithFolder:(NSString *)folder
                                                 uids:(MCOIndexSet *)uids
                                                 kind:(MCOIMAPStoreFlagsRequestKind)kind
                                                flags:(MCOMessageFlag)flags;
 
+// Returns an operation to change labels of messages.
+// The operation needs to be started.
 - (MCOIMAPOperation *) storeLabelsOperationWithFolder:(NSString *)folder
                                                  uids:(MCOIndexSet *)uids
                                                  kind:(MCOIMAPStoreFlagsRequestKind)kind
                                                labels:(NSArray *)labels;
 
+// Returns an operation to search for messages with a simple match.
+// The operation needs to be started.
 - (MCOIMAPSearchOperation *) searchOperationWithFolder:(NSString *)folder
                                                   kind:(MCOIMAPSearchKind)kind
                                           searchString:(NSString *)searchString;
 
+// Returns an operation to search for messages.
+// The operation needs to be started.
 - (MCOIMAPSearchOperation *) searchExpressionOperationWithFolder:(NSString *)folder
                                                       expression:(MCOIMAPSearchExpression *)expression;
 
+// Returns an operation to wait for something to happen in the folder.
+// The operation needs to be started.
 - (MCOIMAPIdleOperation *) idleOperationWithFolder:(NSString *)folder
                                       lastKnownUID:(uint32_t)lastKnownUID;
 
+// Returns an operation to fetch the list of namespaces.
+// The operation needs to be started.
 - (MCOIMAPFetchNamespaceOperation *) fetchNamespaceOperation;
 
+// Returns an operation to send/get identity.
+// The operation needs to be started.
 - (MCOIMAPIdentityOperation *) identityOperationWithVendor:(NSString *)vendor
                                                       name:(NSString *)name
                                                    version:(NSString *)version;
 
+// Returns an operation that will check whether the IMAP account is valid.
+// The operation needs to be started.
+//
+// {
+//   ...
+//   MCOIMAPOperation * op [session checkAccountOperation];
+//   [op start:^(NSError *error) {
+//        ...
+//   }]];
+//
 - (MCOIMAPOperation *) checkAccountOperation;
 
+// Returns an operation to request capabilities of the server.
+// The operation needs to be started.
 - (MCOIMAPCapabilityOperation *) capabilityOperation;
 
 @end
diff --git a/src/objc/imap/MCOIMAPSession.mm b/src/objc/imap/MCOIMAPSession.mm
index e075ba0f..0be1afa3 100644
--- a/src/objc/imap/MCOIMAPSession.mm
+++ b/src/objc/imap/MCOIMAPSession.mm
@@ -55,6 +55,8 @@ MCO_OBJC_SYNTHESIZE_SCALAR(NSTimeInterval, time_t, setTimeout, timeout)
 MCO_OBJC_SYNTHESIZE_BOOL(setCheckCertificateEnabled, isCheckCertificateEnabled)
 MCO_OBJC_SYNTHESIZE_BOOL(setVoIPEnabled, isVoIPEnabled)
 MCO_OBJC_SYNTHESIZE_SCALAR(char, char, setDelimiter, delimiter)
+MCO_OBJC_SYNTHESIZE_SCALAR(BOOL, BOOL, setAllowsFolderConcurrentAccessEnabled, allowsFolderConcurrentAccessEnabled)
+MCO_OBJC_SYNTHESIZE_SCALAR(unsigned int, unsigned int, setMaximumConnections, maximumConnections)
 
 #pragma mark - Operations
 
diff --git a/src/objc/pop/MCOPOPFetchHeaderOperation.h b/src/objc/pop/MCOPOPFetchHeaderOperation.h
index b062904a..d395df5b 100644
--- a/src/objc/pop/MCOPOPFetchHeaderOperation.h
+++ b/src/objc/pop/MCOPOPFetchHeaderOperation.h
@@ -19,7 +19,13 @@
 @class MCOMessageHeader;
 
 @interface MCOPOPFetchHeaderOperation : MCOPOPOperation
-- (void)start:(void (^)(NSError *error, MCOMessageHeader * header))completionBlock;
+
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error and the content of the fetched header.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// header will be nil.
+- (void) start:(void (^)(NSError * error, MCOMessageHeader * header))completionBlock;
+
 @end
 
 #endif
diff --git a/src/objc/pop/MCOPOPFetchMessageOperation.h b/src/objc/pop/MCOPOPFetchMessageOperation.h
index 56857a73..86149e08 100644
--- a/src/objc/pop/MCOPOPFetchMessageOperation.h
+++ b/src/objc/pop/MCOPOPFetchMessageOperation.h
@@ -19,11 +19,15 @@ typedef void (^MCOPOPOperationProgressBlock)(unsigned int current, unsigned int
 
 @interface MCOPOPFetchMessageOperation : MCOPOPOperation
 
-// This block will be called during the progression of the download of the message
+// This block will be called during the progression while downloading the message
 // when some bytes have been downloaded from the network.
 @property (nonatomic, copy) MCOPOPOperationProgressBlock progress;
 
-- (void)start:(void (^)(NSError *error, NSData * messageData))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error and the fetched message data.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// messageData will be nil.
+- (void) start:(void (^)(NSError * error, NSData * messageData))completionBlock;
 
 @end
 
diff --git a/src/objc/pop/MCOPOPFetchMessagesOperation.h b/src/objc/pop/MCOPOPFetchMessagesOperation.h
index ffbf623b..caad35b5 100644
--- a/src/objc/pop/MCOPOPFetchMessagesOperation.h
+++ b/src/objc/pop/MCOPOPFetchMessagesOperation.h
@@ -17,7 +17,12 @@
 
 @interface MCOPOPFetchMessagesOperation : MCOPOPOperation
 
-- (void)start:(void (^)(NSError *error, NSArray * messages))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error and the fetched messages list.
+// Messages will be an array of MCOPOPMessageInfo.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+// messageData will be nil.
+- (void) start:(void (^)(NSError * error, NSArray * /* MCOPOPMessageInfo */ messages))completionBlock;
 
 @end
 
diff --git a/src/objc/pop/MCOPOPOperation.h b/src/objc/pop/MCOPOPOperation.h
index 9eaf7fff..656b57a1 100644
--- a/src/objc/pop/MCOPOPOperation.h
+++ b/src/objc/pop/MCOPOPOperation.h
@@ -17,7 +17,11 @@
 // See MCOPOPSession for more info.
 
 @interface MCOPOPOperation : MCOOperation
-- (void)start:(void (^)(NSError *error))completionBlock;
+
+// On success, the completion block will be called with nil as error.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+- (void) start:(void (^)(NSError * error))completionBlock;
+
 @end
 
 #endif
diff --git a/src/objc/pop/MCOPOPSession.h b/src/objc/pop/MCOPOPSession.h
index 7b59256d..0041e561 100644
--- a/src/objc/pop/MCOPOPSession.h
+++ b/src/objc/pop/MCOPOPSession.h
@@ -53,6 +53,7 @@
 @property (nonatomic, assign, getter=isCheckCertificateEnabled) BOOL checkCertificateEnabled;
 
 // Returns an operation that will fetch the list of messages.
+// The operation needs to be started.
 //
 // {
 //   ...
@@ -65,6 +66,7 @@
 - (MCOPOPFetchMessagesOperation *) fetchMessagesOperation;
 
 // Returns an operation that will fetch the header of the given message.
+// The operation needs to be started.
 //
 // {
 //   ...
@@ -76,6 +78,7 @@
 - (MCOPOPFetchHeaderOperation *) fetchHeaderOperationWithIndex:(unsigned int)index;
 
 // Returns an operation that will fetch the content of the given message.
+// The operation needs to be started.
 //
 // {
 //   ...
@@ -88,6 +91,7 @@
 
 // Returns an operation that will delete the given messages.
 // Will disconnect when finished.
+// The operation needs to be started.
 //
 // {
 //   ...
diff --git a/src/objc/smtp/MCOSMTPOperation.h b/src/objc/smtp/MCOSMTPOperation.h
index 1b3b4b83..32d98dc8 100644
--- a/src/objc/smtp/MCOSMTPOperation.h
+++ b/src/objc/smtp/MCOSMTPOperation.h
@@ -15,7 +15,12 @@
 // This is an asynchronous SMTP operation.
 
 @interface MCOSMTPOperation : MCOOperation
-- (void)start:(void (^)(NSError *error))completionBlock;
+
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+- (void) start:(void (^)(NSError * error))completionBlock;
+
 @end
 
 #endif
diff --git a/src/objc/smtp/MCOSMTPSendOperation.h b/src/objc/smtp/MCOSMTPSendOperation.h
index 2174df91..e8a0f6b5 100644
--- a/src/objc/smtp/MCOSMTPSendOperation.h
+++ b/src/objc/smtp/MCOSMTPSendOperation.h
@@ -18,11 +18,14 @@ typedef void (^MCOSMTPOperationProgressBlock)(unsigned int current, unsigned int
 
 @interface MCOSMTPSendOperation : MCOSMTPOperation
 
-// This block will be called during the progression of the send of the message
+// This block will be called during the progression while sending the message
 // when some bytes have been sent to the network.
 @property (nonatomic, copy) MCOSMTPOperationProgressBlock progress;
 
-- (void)start:(void (^)(NSError *error))completionBlock;
+// Starts the asynchronous operation.
+// On success, the completion block will be called with nil as error.
+// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h.
+- (void) start:(void (^)(NSError * error))completionBlock;
 
 @end
 
diff --git a/src/objc/smtp/MCOSMTPSession.h b/src/objc/smtp/MCOSMTPSession.h
index b9fb9225..3b29ddf7 100644
--- a/src/objc/smtp/MCOSMTPSession.h
+++ b/src/objc/smtp/MCOSMTPSession.h
@@ -55,6 +55,7 @@
 @property (nonatomic, assign, getter=isUseHeloIPEnabled) BOOL useHeloIPEnabled;
 
 // Returns an operation that will send the given message through SMTP.
+// The operation needs to be started.
 // It will use the recipient set in the message data (To, Cc and Bcc).
 // It will also filter out Bcc from the content of the message.
 //
@@ -69,6 +70,7 @@
 - (MCOSMTPSendOperation *) sendOperationWithData:(NSData *)messageData;
 
 // Returns an operation that will check whether the SMTP account is valid.
+// The operation needs to be started.
 //
 // {
 //   ...
diff --git a/src/objc/utils/MCOOperation+Private.h b/src/objc/utils/MCOOperation+Private.h
index 785abd91..94706fdb 100644
--- a/src/objc/utils/MCOOperation+Private.h
+++ b/src/objc/utils/MCOOperation+Private.h
@@ -20,9 +20,9 @@ namespace mailcore {
 
 @interface MCOOperation (Private)
 #ifdef __cplusplus
-- (id)initWithMCOperation:(mailcore::Operation *)op;
+- (id) initWithMCOperation:(mailcore::Operation *)op;
 #endif
-- (void)start;
+- (void) start;
 @end
 
 #endif
diff --git a/src/objc/utils/MCOOperation.h b/src/objc/utils/MCOOperation.h
index 7893f917..3f6b42c5 100644
--- a/src/objc/utils/MCOOperation.h
+++ b/src/objc/utils/MCOOperation.h
@@ -18,10 +18,10 @@
 
 // This methods is called on the main thread when the asynchronous operation is finished.
 // Needs to be overriden by subclasses.
-- (void)operationCompleted;
+- (void) operationCompleted;
 
 // Cancel the operation.
-- (void)cancel;
+- (void) cancel;
 
 @end
 
diff --git a/src/objc/utils/MCOOperation.mm b/src/objc/utils/MCOOperation.mm
index c40f9fa7..37146b39 100644
--- a/src/objc/utils/MCOOperation.mm
+++ b/src/objc/utils/MCOOperation.mm
@@ -56,7 +56,7 @@ public:
     return _operation;
 }
 
-- (id)initWithMCOperation:(Operation *)op
+- (id) initWithMCOperation:(Operation *)op
 {
     self = [super init];
     
@@ -69,19 +69,19 @@ public:
     return self;
 }
 
-- (void)dealloc
+- (void) dealloc
 {
     _operation->release();
     _callback->release();
     [super dealloc];
 }
 
-- (BOOL)isCancelled
+- (BOOL) isCancelled
 {
     return MCO_NATIVE_INSTANCE->isCancelled();
 }
 
-- (void)cancel
+- (void) cancel
 {
     if (_started) {
         _started = NO;
@@ -90,21 +90,21 @@ public:
     _operation->cancel();
 }
 
-- (void)start
+- (void) start
 {
     _started = YES;
     [self retain];
     _operation->start();
 }
 
-- (void)_operationCompleted
+- (void) _operationCompleted
 {
     _started = NO;
     [self operationCompleted];
     [self release];
 }
 
-- (void)operationCompleted
+- (void) operationCompleted
 {
 }
 
diff --git a/src/objc/utils/NSError+MCO.h b/src/objc/utils/NSError+MCO.h
index baf48f45..d71b3135 100644
--- a/src/objc/utils/NSError+MCO.h
+++ b/src/objc/utils/NSError+MCO.h
@@ -12,7 +12,7 @@
 
 @interface NSError (MCO)
 #ifdef __cplusplus
-+ (NSError *)mco_errorWithErrorCode:(mailcore::ErrorCode)code;
++ (NSError *) mco_errorWithErrorCode:(mailcore::ErrorCode)code;
 #endif
 @end
 
diff --git a/src/objc/utils/NSError+MCO.mm b/src/objc/utils/NSError+MCO.mm
index 966d41bb..c9f4f998 100644
--- a/src/objc/utils/NSError+MCO.mm
+++ b/src/objc/utils/NSError+MCO.mm
@@ -5,14 +5,17 @@
 
 #import "NSError+MCO.h"
 
+#import "MCOConstants.h"
+
 @implementation NSError (MCO)
 + (NSError *)mco_errorWithErrorCode:(mailcore::ErrorCode)code {
     if (code == mailcore::ErrorNone) {
         return nil;
     }
 
-    NSError *error = [NSError errorWithDomain:@"MailCore" code:(int)code
-                                     userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"Unknown error: %d", (int)code]}];
+    NSError *error = [NSError errorWithDomain:MCOErrorDomain
+                                         code:(int)code
+                                     userInfo:nil];
     return error;
 }
 @end
\ No newline at end of file