Merge branch 'master' of github.com:silenteh/mailcore2

49 files changed, 1241 insertions, 1057 deletions

diff --git a/src/core/basetypes/MCString.cc b/src/core/basetypes/MCString.cc
index 6710e599..23989583 100644
--- a/src/core/basetypes/MCString.cc
+++ b/src/core/basetypes/MCString.cc
@@ -1975,6 +1975,7 @@ String * String::substringWithRange(Range range)
 }
 
 static chash * uniquedStringHash = NULL;
+static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
 
 static void initUniquedStringHash()
 {
@@ -1991,14 +1992,17 @@ String * String::uniquedStringWithUTF8Characters(const char * UTF8Characters)
     pthread_once(&once, initUniquedStringHash);
     key.data = (void *) UTF8Characters;
     key.len = (unsigned int) strlen(UTF8Characters);
+    pthread_mutex_lock(&lock);
     r = chash_get(uniquedStringHash, &key, &value);
     if (r == 0) {
+        pthread_mutex_unlock(&lock);
         return (String *) value.data;
     }
     else {
         value.data = new String(UTF8Characters);
         value.len = 0;
         chash_set(uniquedStringHash, &key, &value, NULL);
+        pthread_mutex_unlock(&lock);
         return (String *) value.data;
     }
 }
diff --git a/src/objc/abstract/MCOAbstractMessage.h b/src/objc/abstract/MCOAbstractMessage.h
index aa47d15a..a26d5aac 100644
--- a/src/objc/abstract/MCOAbstractMessage.h
+++ b/src/objc/abstract/MCOAbstractMessage.h
@@ -17,16 +17,19 @@
 
 @interface MCOAbstractMessage : NSObject
 
-// Header of the message.
+/** Header of the message. */
 @property (nonatomic, strong) MCOMessageHeader * header;
 
-// Returns the part with the given Content-ID.
+/** Returns the part with the given Content-ID.*/
 - (MCOAbstractPart *) partForContentID:(NSString *)contentID;
 
-// Returns the part with the given unique identifier.
+/** Returns the part with the given unique identifier.*/
 - (MCOAbstractPart *) partForUniqueID:(NSString *)uniqueID;
 
+/** All attachments in the message */
 - (NSArray *) attachments;
+
+/** All HTML bodies */
 - (NSArray *) htmlInlineAttachments;
 
 @end
diff --git a/src/objc/abstract/MCOAbstractMultipart.h b/src/objc/abstract/MCOAbstractMultipart.h
index 38f9dbe3..e43a3e41 100644
--- a/src/objc/abstract/MCOAbstractMultipart.h
+++ b/src/objc/abstract/MCOAbstractMultipart.h
@@ -15,7 +15,7 @@
 
 @interface MCOAbstractMultipart : MCOAbstractPart
 
-// Returns the subparts of that multipart.
+/** Returns the subparts of that multipart.*/
 @property (nonatomic, copy) NSArray * /* MCOAbstractPart */ parts;
 
 @end
diff --git a/src/objc/abstract/MCOAbstractPart.h b/src/objc/abstract/MCOAbstractPart.h
index 770808e0..0269347a 100644
--- a/src/objc/abstract/MCOAbstractPart.h
+++ b/src/objc/abstract/MCOAbstractPart.h
@@ -39,43 +39,43 @@ typedef enum {
 
 @interface MCOAbstractPart : NSObject
 
-// Returns type of the part (single / message part / multipart/mixed,
-// multipart/related, multipart/alternative). See MCOPartType.
+/** Returns type of the part (single / message part / multipart/mixed,
+ multipart/related, multipart/alternative). See MCOPartType.*/
 @property (nonatomic, assign) MCOPartType partType;
 
-// Returns filename of the part.
+/** Returns filename of the part.*/
 @property (nonatomic, copy) NSString * filename;
 
-// Returns MIME type of the part. For example application/data.
+/** Returns MIME type of the part. For example application/data.*/
 @property (nonatomic, copy) NSString * mimeType;
 
-// Returns charset of the part in case it's a text single part.
+/** Returns charset of the part in case it's a text single part.*/
 @property (nonatomic, copy) NSString * charset;
 
-// Returns the unique ID generated for this part.
-// It's a unique identifier that's created when the object is created manually
-// or created by the parser.
+/** Returns the unique ID generated for this part.
+ It's a unique identifier that's created when the object is created manually
+ or created by the parser.*/
 @property (nonatomic, copy) NSString * uniqueID;
 
-// Returns the value of the Content-ID field of the part.
+/** Returns the value of the Content-ID field of the part.*/
 @property (nonatomic, copy) NSString * contentID;
 
-// Returns the value of the Content-Location field of the part.
+/** Returns the value of the Content-Location field of the part.*/
 @property (nonatomic, copy) NSString * contentLocation;
 
-// Returns whether the part is an explicit inline attachment.
+/** Returns whether the part is an explicit inline attachment.*/
 @property (nonatomic, assign, getter=isInlineAttachment) BOOL inlineAttachment;
 
-// Returns the owner message of the part.
+/** Returns the owner message of the part.*/
 @property (nonatomic, weak) MCOAbstractMessage * message;
 
-// Returns the part with the given Content-ID among this part and its subparts.
+/** Returns the part with the given Content-ID among this part and its subparts.*/
 - (MCOAbstractPart *) partForContentID:(NSString *)contentID;
 
-// Returns the part with the given unique identifier among this part and its subparts.
+/** Returns the part with the given unique identifier among this part and its subparts.*/
 - (MCOAbstractPart *) partForUniqueID:(NSString *)uniqueID;
 
-// Returns a string representation of the data according to charset.
+/** Returns a string representation of the data according to charset.*/
 - (NSString *) decodedStringForData:(NSData *)data;
 
 @end
diff --git a/src/objc/abstract/MCOAddress.h b/src/objc/abstract/MCOAddress.h
index c7552676..8e409589 100644
--- a/src/objc/abstract/MCOAddress.h
+++ b/src/objc/abstract/MCOAddress.h
@@ -14,56 +14,66 @@
 
 @interface MCOAddress : NSObject <NSCopying>
 
-// Creates an address with a display name and a mailbox.
-// Example: [MCOAddress addressWithDisplayName:@"DINH Viêt Hoà" mailbox:@"hoa@etpan.org"]
+/** Creates an address with a display name and a mailbox.
+
+    Example: [MCOAddress addressWithDisplayName:@"DINH Viêt Hoà" mailbox:@"hoa@etpan.org"] */
 + (MCOAddress *) addressWithDisplayName:(NSString *)displayName
                                 mailbox:(NSString *)mailbox;
 
-// Creates an address with only a mailbox.
-// Example: [MCOAddress addressWithMailbox:@"hoa@etpan.org"]
+/** Creates an address with only a mailbox.
+
+    Example: [MCOAddress addressWithMailbox:@"hoa@etpan.org"]*/
 + (MCOAddress *) addressWithMailbox:(NSString *)mailbox;
 
-// Creates an address with a RFC822 string.
-// Example: [MCOAddress addressWithRFC822String:@"DINH Vi=C3=AAt Ho=C3=A0 <hoa@etpan.org>"]
+/** Creates an address with a RFC822 string.
+
+    Example: [MCOAddress addressWithRFC822String:@"DINH Vi=C3=AAt Ho=C3=A0 <hoa@etpan.org>"]*/
 + (MCOAddress *) addressWithRFC822String:(NSString *)RFC822String;
 
-// Creates an address with a non-MIME-encoded RFC822 string.
-// Example: [MCOAddress addressWithRFC822String:@"DINH Viêt Hoà <hoa@etpan.org>"]
+/** Creates an address with a non-MIME-encoded RFC822 string.
+
+    Example: [MCOAddress addressWithRFC822String:@"DINH Viêt Hoà <hoa@etpan.org>"]*/
 + (MCOAddress *) addressWithNonEncodedRFC822String:(NSString *)nonEncodedRFC822String;
 
-// Returns an NSArray of MCOAddress objects that contain the parsed
-// forms of the RFC822 encoded addresses.
-// For example: @[ @"DINH Vi=C3=AAt Ho=C3=A0 <hoa@etpan.org>" ]
+/** 
+ Returns an NSArray of MCOAddress objects that contain the parsed
+ forms of the RFC822 encoded addresses.
+
+ For example: @[ @"DINH Vi=C3=AAt Ho=C3=A0 <hoa@etpan.org>" ]*/
 + (NSArray *) addressesWithRFC822String:(NSString *)string;
 
-// Returns an NSArray of MCOAddress objects that contain the parsed
-// forms of non-encoded RFC822 addresses.
-// For example: @[ "DINH Viêt Hoà <hoa@etpan.org>" ]
+/** 
+ Returns an NSArray of MCOAddress objects that contain the parsed
+ forms of non-encoded RFC822 addresses.
+
+ For example: @[ "DINH Viêt Hoà <hoa@etpan.org>" ]*/
 + (NSArray *) addressesWithNonEncodedRFC822String:(NSString *)string;
 
 
-// Returns the display name of the address.
+/** Returns the display name of the address.*/
 @property (nonatomic, copy) NSString * displayName;
 
-// Returns the mailbox of the address.
+/** Returns the mailbox of the address.*/
 @property (nonatomic, copy) NSString * mailbox;
 
-// Returns the RFC822 encoding of the address.
-// For example: "DINH Vi=C3=AAt Ho=C3=A0 <hoa@etpan.org>"
+/** Returns the RFC822 encoding of the address.
+
+    For example: "DINH Vi=C3=AAt Ho=C3=A0 <hoa@etpan.org>"*/
 - (NSString *) RFC822String;
 
-// Returns the non-MIME-encoded RFC822 encoding of the address.
-// For example: "DINH Viêt Hoà <hoa@etpan.org>"
+/** Returns the non-MIME-encoded RFC822 encoding of the address.
+
+    For example: "DINH Viêt Hoà <hoa@etpan.org>"*/
 - (NSString *) nonEncodedRFC822String;
 
 @end
 
-@interface NSArray (MCONSArray)
+@interface NSArray (MCOAddress)
 
-// Returns the RFC822 encoding of the addresses.
+/** Returns the RFC822 encoding of the addresses.*/
 - (NSString *) mco_RFC822StringForAddresses;
 
-// Returns the non-MIME-encoded RFC822 of the addresses.
+/** Returns the non-MIME-encoded RFC822 of the addresses.*/
 - (NSString *) mco_nonEncodedRFC822StringForAddresses;
 
 @end
diff --git a/src/objc/abstract/MCOAddress.mm b/src/objc/abstract/MCOAddress.mm
index 7a398421..1cb37e62 100644
--- a/src/objc/abstract/MCOAddress.mm
+++ b/src/objc/abstract/MCOAddress.mm
@@ -147,7 +147,7 @@ MCO_OBJC_SYNTHESIZE_STRING(setMailbox, mailbox)
 
 @end
 
-@implementation NSArray (MCONSArray)
+@implementation NSArray (MCOAddress)
 
 - (NSString *) mco_RFC822StringForAddresses
 {
diff --git a/src/objc/abstract/MCOConstants.h b/src/objc/abstract/MCOConstants.h
index a8cf7bd4..6f9dd446 100644
--- a/src/objc/abstract/MCOConstants.h
+++ b/src/objc/abstract/MCOConstants.h
@@ -2,321 +2,321 @@
 
 #define __MAILCORE_MCOCONSTANTS_H_
 
-// It's the connection type.
+/** It's the connection type.*/
 typedef enum {
-    // Clear-text connection for the protocol.
+    /** Clear-text connection for the protocol.*/
     MCOConnectionTypeClear             = 1 << 0,
-    // Clear-text connection at the beginning, then switch to encrypted connection using TLS/SSL
-    // on the same TCP connection.
+    /** Clear-text connection at the beginning, then switch to encrypted connection using TLS/SSL*/
+    /** on the same TCP connection.*/
     MCOConnectionTypeStartTLS          = 1 << 1,
-    // Encrypted connection using TLS/SSL.
+    /** Encrypted connection using TLS/SSL.*/
     MCOConnectionTypeTLS               = 1 << 2,
 } MCOConnectionType;
 
-// It's the authentication type.
+/** It's the authentication type.*/
 typedef enum {
-    // Default authentication scheme of the protocol.
+    /** Default authentication scheme of the protocol.*/
     MCOAuthTypeSASLNone          = 0,
-    // CRAM-MD5 authentication RFC 2195.
+    /** CRAM-MD5 authentication RFC 2195.*/
     MCOAuthTypeSASLCRAMMD5       = 1 << 0,
-    // PLAIN authentication RFC 4616.
+    /** PLAIN authentication RFC 4616.*/
     MCOAuthTypeSASLPlain         = 1 << 1,
-    // GSSAPI authentication.
+    /** GSSAPI authentication.*/
     MCOAuthTypeSASLGSSAPI        = 1 << 2,
-    // DIGEST-MD5 authentication RFC 2831.
+    /** DIGEST-MD5 authentication RFC 2831.*/
     MCOAuthTypeSASLDIGESTMD5     = 1 << 3,
-    // LOGIN authentication http://tools.ietf.org/id/draft-murchison-sasl-login-00.txt
+    /** LOGIN authentication http://tools.ietf.org/id/draft-murchison-sasl-login-00.txt*/
     MCOAuthTypeSASLLogin         = 1 << 4,
-    // Secure Remote Password Authentication http://tools.ietf.org/html/draft-burdis-cat-srp-sasl-08
+    /** Secure Remote Password Authentication http://tools.ietf.org/html/draft-burdis-cat-srp-sasl-08*/
     MCOAuthTypeSASLSRP           = 1 << 5,
-    // NTLM authentication.
+    /** NTLM authentication.*/
     MCOAuthTypeSASLNTLM          = 1 << 6,
-    // Kerberos 4 authentication.
+    /** Kerberos 4 authentication.*/
     MCOAuthTypeSASLKerberosV4    = 1 << 7,
 } MCOAuthType;
 
-// It's the IMAP flags of the folder.
+/** It's the IMAP flags of the folder.*/
 typedef enum {
     MCOIMAPFolderFlagNone        = 0,
-    // \Marked
+    /** \Marked*/
     MCOIMAPFolderFlagMarked      = 1 << 0,
-    // \Unmarked
+    /** \Unmarked*/
     MCOIMAPFolderFlagUnmarked    = 1 << 1,
-    // \NoSelect: When a folder can't be selected.
+    /** \NoSelect: When a folder can't be selected.*/
     MCOIMAPFolderFlagNoSelect    = 1 << 2,
-    // \NoInferiors: When the folder has no children.
+    /** \NoInferiors: When the folder has no children.*/
     MCOIMAPFolderFlagNoInferiors = 1 << 3,
-    // \Inbox: When the folder is the inbox.
+    /** \Inbox: When the folder is the inbox.*/
     MCOIMAPFolderFlagInbox       = 1 << 4,
-    // \Sent: When the folder is the sent folder.
+    /** \Sent: When the folder is the sent folder.*/
     MCOIMAPFolderFlagSentMail    = 1 << 5,
-    // \Starred: When the folder is the starred folder
+    /** \Starred: When the folder is the starred folder*/
     MCOIMAPFolderFlagStarred     = 1 << 6,
-    // \AllMail: When the folder is all mail.
+    /** \AllMail: When the folder is all mail.*/
     MCOIMAPFolderFlagAllMail     = 1 << 7,
-    // \Trash: When the folder is the trash.
+    /** \Trash: When the folder is the trash.*/
     MCOIMAPFolderFlagTrash       = 1 << 8,
-    // \Drafts: When the folder is the drafts folder.
+    /** \Drafts: When the folder is the drafts folder.*/
     MCOIMAPFolderFlagDrafts      = 1 << 9,
-    // \Spam: When the folder is the spam folder.
+    /** \Spam: When the folder is the spam folder.*/
     MCOIMAPFolderFlagSpam        = 1 << 10,
-    // \Important: When the folder is the important folder.
+    /** \Important: When the folder is the important folder.*/
     MCOIMAPFolderFlagImportant   = 1 << 11,
-    // \Archive: When the folder is archive.
+    /** \Archive: When the folder is archive.*/
     MCOIMAPFolderFlagArchive     = 1 << 12,
-    // \All: When the folder contains all mails, similar to \AllMail.
+    /** \All: When the folder contains all mails, similar to \AllMail.*/
     MCOIMAPFolderFlagAll         = MCOIMAPFolderFlagAllMail,
-    // \Junk: When the folder is the spam folder.
+    /** \Junk: When the folder is the spam folder.*/
     MCOIMAPFolderFlagJunk        = MCOIMAPFolderFlagSpam,
-    // \Flagged: When the folder contains all the flagged emails.
+    /** \Flagged: When the folder contains all the flagged emails.*/
     MCOIMAPFolderFlagFlagged     = MCOIMAPFolderFlagStarred,
 } MCOIMAPFolderFlag;
 
-// It's the flags of a message.
+/** It's the flags of a message.*/
 typedef enum {
     MCOMessageFlagNone          = 0,
-    // Seen/Read flag.
+    /** Seen/Read flag.*/
     MCOMessageFlagSeen          = 1 << 0,
-    // Replied/Answered flag.
+    /** Replied/Answered flag.*/
     MCOMessageFlagAnswered      = 1 << 1,
-    // Flagged/Starred flag.
+    /** Flagged/Starred flag.*/
     MCOMessageFlagFlagged       = 1 << 2,
-    // Deleted flag.
+    /** Deleted flag.*/
     MCOMessageFlagDeleted       = 1 << 3,
-    // Draft flag.
+    /** Draft flag.*/
     MCOMessageFlagDraft         = 1 << 4,
-    // $MDNSent flag.
+    /** $MDNSent flag.*/
     MCOMessageFlagMDNSent       = 1 << 5,
-    // $Forwarded flag.
+    /** $Forwarded flag.*/
     MCOMessageFlagForwarded     = 1 << 6,
-    // $SubmitPending flag.
+    /** $SubmitPending flag.*/
     MCOMessageFlagSubmitPending = 1 << 7,
-    // $Submitted flag.
+    /** $Submitted flag.*/
     MCOMessageFlagSubmitted     = 1 << 8,
 } MCOMessageFlag;
 
-// It's the encoding of a part.
+/** It's the encoding of a part.*/
 typedef enum {
-    // 7bit encoding.
-    MCOEncoding7Bit = 0,            // should match MAILIMAP_BODY_FLD_ENC_7BIT
-    // 8bit encoding.
-    MCOEncoding8Bit = 1,            // should match MAILIMAP_BODY_FLD_ENC_8BIT
-    // binary encoding.
-    MCOEncodingBinary = 2,          // should match MAILIMAP_BODY_FLD_ENC_BINARY
-    // base64 encoding.
-    MCOEncodingBase64 = 3,          // should match MAILIMAP_BODY_FLD_ENC_BASE64
-    // quoted-printable encoding.
-    MCOEncodingQuotedPrintable = 4, // should match MAILIMAP_BODY_FLD_ENC_QUOTED_PRINTABLE
-    // other encoding.
-    MCOEncodingOther = 5,           // should match MAILIMAP_BODY_FLD_ENC_OTHER
+    /** 7bit encoding.*/
+    MCOEncoding7Bit = 0,            /** should match MAILIMAP_BODY_FLD_ENC_7BIT*/
+    /** 8bit encoding.*/
+    MCOEncoding8Bit = 1,            /** should match MAILIMAP_BODY_FLD_ENC_8BIT*/
+    /** binary encoding.*/
+    MCOEncodingBinary = 2,          /** should match MAILIMAP_BODY_FLD_ENC_BINARY*/
+    /** base64 encoding.*/
+    MCOEncodingBase64 = 3,          /** should match MAILIMAP_BODY_FLD_ENC_BASE64*/
+    /** quoted-printable encoding.*/
+    MCOEncodingQuotedPrintable = 4, /** should match MAILIMAP_BODY_FLD_ENC_QUOTED_PRINTABLE*/
+    /** other encoding.*/
+    MCOEncodingOther = 5,           /** should match MAILIMAP_BODY_FLD_ENC_OTHER*/
     
-    // Negative values should be used for encoding not supported by libetpan.
+    /** Negative values should be used for encoding not supported by libetpan.*/
     
-    // UUEncode encoding.
+    /** UUEncode encoding.*/
     MCOEncodingUUEncode = -1
 } MCOEncoding;
 
-// It's the information to fetch for a given message in the IMAP FETCH request.
+/** It's the information to fetch for a given message in the IMAP FETCH request.*/
 typedef enum {
-    // UID of the message.
-    MCOIMAPMessagesRequestKindUid           = 0, // This is the default and it's always fetched
-    // Flags of the message.
+    /** UID of the message.*/
+    MCOIMAPMessagesRequestKindUid           = 0, /** This is the default and it's always fetched*/
+    /** Flags of the message.*/
     MCOIMAPMessagesRequestKindFlags         = 1 << 0,
-    // Headers of the message (parsed by the server).
+    /** Headers of the message (parsed by the server).*/
     MCOIMAPMessagesRequestKindHeaders       = 1 << 1,
-    // MIME structure of the message.
+    /** MIME structure of the message.*/
     MCOIMAPMessagesRequestKindStructure     = 1 << 2,
-    // Received date.
+    /** Received date.*/
     MCOIMAPMessagesRequestKindInternalDate  = 1 << 3,
-    // Headers through headers data.
+    /** Headers through headers data.*/
     MCOIMAPMessagesRequestKindFullHeaders   = 1 << 4,
-    // Subject of the message.
+    /** Subject of the message.*/
     MCOIMAPMessagesRequestKindHeaderSubject = 1 << 5,
-    // Gmail Labels.
+    /** Gmail Labels.*/
     MCOIMAPMessagesRequestKindGmailLabels   = 1 << 6,
 } MCOIMAPMessagesRequestKind;
 
-// It defines the behavior of the STORE flags request.
+/** It defines the behavior of the STORE flags request.*/
 typedef enum {
-    // Add the given flags.
+    /** Add the given flags.*/
     MCOIMAPStoreFlagsRequestKindAdd,
-    // Remove the given flags.
+    /** Remove the given flags.*/
     MCOIMAPStoreFlagsRequestKindRemove,
-    // Set the given flags.
+    /** Set the given flags.*/
     MCOIMAPStoreFlagsRequestKindSet,
 } MCOIMAPStoreFlagsRequestKind;
 
-// It's the search type.
+/** It's the search type.*/
 typedef enum {
-    // No search.
+    /** No search.*/
     MCOIMAPSearchKindNone,
-    // Match sender.
+    /** Match sender.*/
     MCOIMAPSearchKindFrom,
-    // Match recipient.
+    /** Match recipient.*/
     MCOIMAPSearchKindRecipient,
-    // Match subject.
+    /** Match subject.*/
     MCOIMAPSearchKindSubject,
-    // Match content of the message.
+    /** Match content of the message.*/
     MCOIMAPSearchKindContent,
-    // Match headers of the message.
+    /** Match headers of the message.*/
     MCOIMAPSearchKindHeader,
-    // Or expresssion.
+    /** Or expresssion.*/
     MCOIMAPSearchKindOr,
-    // And expression.
+    /** And expression.*/
     MCOIMAPSearchKindAnd,
 } MCOIMAPSearchKind;
 
-// Keys for the namespace dictionary.
+/** 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.
+/** This is the constants for the IMAP capabilities.*/
+/** See corresponding RFC for more information.*/
 typedef enum {
-    // ACL Capability.
+    /** ACL Capability.*/
     MCOIMAPCapabilityACL,
-    // BINARY Capability.
+    /** BINARY Capability.*/
     MCOIMAPCapabilityBinary,
-    // CATENATE Capability.
+    /** CATENATE Capability.*/
     MCOIMAPCapabilityCatenate,
-    // CHILDREN Capability.
+    /** CHILDREN Capability.*/
     MCOIMAPCapabilityChildren,
-    // COMPRESS Capability.
+    /** COMPRESS Capability.*/
     MCOIMAPCapabilityCompressDeflate,
-    // CONDSTORE Capability.
+    /** CONDSTORE Capability.*/
     MCOIMAPCapabilityCondstore,
-    // ENABLE Capability.
+    /** ENABLE Capability.*/
     MCOIMAPCapabilityEnable,
-    // IDLE Capability.
+    /** IDLE Capability.*/
     MCOIMAPCapabilityIdle,
-    // ID Capability.
+    /** ID Capability.*/
     MCOIMAPCapabilityId,
-    // LITERAL+ Capability.
+    /** LITERAL+ Capability.*/
     MCOIMAPCapabilityLiteralPlus,
-    // MULTIAPPEND Capability.
+    /** MULTIAPPEND Capability.*/
     MCOIMAPCapabilityMultiAppend,
-    // NAMESPACE Capability.
+    /** NAMESPACE Capability.*/
     MCOIMAPCapabilityNamespace,
-    // QRESYNC Capability.
+    /** QRESYNC Capability.*/
     MCOIMAPCapabilityQResync,
-    // QUOTE Capability.
+    /** QUOTE Capability.*/
     MCOIMAPCapabilityQuota,
-    // SORT Capability.
+    /** SORT Capability.*/
     MCOIMAPCapabilitySort,
-    // STARTTLS Capability.
+    /** STARTTLS Capability.*/
     MCOIMAPCapabilityStartTLS,
-    // THREAD=ORDEREDSUBJECT Capability.
+    /** THREAD=ORDEREDSUBJECT Capability.*/
     MCOIMAPCapabilityThreadOrderedSubject,
-    // THREAD=REFERENCES Capability.
+    /** THREAD=REFERENCES Capability.*/
     MCOIMAPCapabilityThreadReferences,
-    // UIDPLUS Capability.
+    /** UIDPLUS Capability.*/
     MCOIMAPCapabilityUIDPlus,
-    // UNSELECT Capability.
+    /** UNSELECT Capability.*/
     MCOIMAPCapabilityUnselect,
-    // XLIST Capability.
+    /** XLIST Capability.*/
     MCOIMAPCapabilityXList,
-    // AUTH=ANONYMOUS Capability.
+    /** AUTH=ANONYMOUS Capability.*/
     MCOIMAPCapabilityAuthAnonymous,
-    // AUTH=CRAM-MD5 Capability.
+    /** AUTH=CRAM-MD5 Capability.*/
     MCOIMAPCapabilityAuthCRAMMD5,
-    // AUTH=DIGEST-MD5 Capability.
+    /** AUTH=DIGEST-MD5 Capability.*/
     MCOIMAPCapabilityAuthDigestMD5,
-    // AUTH=EXTERNAL Capability.
+    /** AUTH=EXTERNAL Capability.*/
     MCOIMAPCapabilityAuthExternal,
-    // AUTH=GSSAPI Capability.
+    /** AUTH=GSSAPI Capability.*/
     MCOIMAPCapabilityAuthGSSAPI,
-    // AUTH=KERBEROSV4 Capability.
+    /** AUTH=KERBEROSV4 Capability.*/
     MCOIMAPCapabilityAuthKerberosV4,
-    // AUTH=LOGIN Capability.
+    /** AUTH=LOGIN Capability.*/
     MCOIMAPCapabilityAuthLogin,
-    // AUTH=NTML Capability.
+    /** AUTH=NTML Capability.*/
     MCOIMAPCapabilityAuthNTLM,
-    // AUTH=OTP Capability.
+    /** AUTH=OTP Capability.*/
     MCOIMAPCapabilityAuthOTP,
-    // AUTH=PLAIN Capability.
+    /** AUTH=PLAIN Capability.*/
     MCOIMAPCapabilityAuthPlain,
-    // AUTH=SKEY Capability.
+    /** AUTH=SKEY Capability.*/
     MCOIMAPCapabilityAuthSKey,
-    // AUTH=SRP Capability.
+    /** AUTH=SRP Capability.*/
     MCOIMAPCapabilityAuthSRP,
 } MCOIMAPCapability;
 
-// Error domain for mailcore.
+/** Error domain for mailcore.*/
 #define MCOErrorDomain @"MCOErrorDomain"
 
-// Here's the list of errors.
+/** Here's the list of errors.*/
 typedef enum {
-    // No error occurred.
+    /** No error occurred.*/
     MCOErrorNone,
-    // An error related to the connection occurred.
-    // It could not connect or it's been disconnected.
+    /** An error related to the connection occurred.*/
+    /** It could not connect or it's been disconnected.*/
     MCOErrorConnection,
-    // TLS/SSL connection was not available.
+    /** TLS/SSL connection was not available.*/
     MCOErrorTLSNotAvailable,
-    // The protocol could not be parsed.
+    /** The protocol could not be parsed.*/
     MCOErrorParse,
-    // Certificate was not valid.
+    /** Certificate was not valid.*/
     MCOErrorCertificate,
-    // An authentication error occurred.
+    /** An authentication error occurred.*/
     MCOErrorAuthentication,
-    // Specific to Gmail: IMAP not enabled.
+    /** Specific to Gmail: IMAP not enabled.*/
     MCOErrorGmailIMAPNotEnabled,
-    // Specific to Gmail: Exceeded bandwidth limit.
+    /** Specific to Gmail: Exceeded bandwidth limit.*/
     MCOErrorGmailExceededBandwidthLimit,
-    // Specific to Gmail: Too many simultaneous connections.
+    /** Specific to Gmail: Too many simultaneous connections.*/
     MCOErrorGmailTooManySimultaneousConnections,
-    // Specific to Mobile Me: Moved to iCloud.
+    /** Specific to Mobile Me: Moved to iCloud.*/
     MCOErrorMobileMeMoved,
-    // Specific to Yahoo: not available.
+    /** Specific to Yahoo: not available.*/
     MCOErrorYahooUnavailable,
-    // Non existant folder, select failed.
+    /** Non existant folder, select failed.*/
     MCOErrorNonExistantFolder,
-    // IMAP: Error occurred while renaming a folder.
+    /** IMAP: Error occurred while renaming a folder.*/
     MCOErrorRename,
-    // IMAP: Error occurred while deleting a folder.
+    /** IMAP: Error occurred while deleting a folder.*/
     MCOErrorDelete,
-    // IMAP: Error occurred while creating a folder.
+    /** IMAP: Error occurred while creating a folder.*/
     MCOErrorCreate,
-    // IMAP: Error occurred while subscribing/unsubcribing to a folder.
+    /** IMAP: Error occurred while subscribing/unsubcribing to a folder.*/
     MCOErrorSubscribe,
-    // IMAP: Error occurred while adding a message to a folder.
+    /** IMAP: Error occurred while adding a message to a folder.*/
     MCOErrorAppend,
-    // IMAP: Error occurred while copying a message.
+    /** IMAP: Error occurred while copying a message.*/
     MCOErrorCopy,
-    // IMAP: Error occurred while expunging.
+    /** IMAP: Error occurred while expunging.*/
     MCOErrorExpunge,
-    // IMAP: Error occurred while fetching messages.
+    /** IMAP: Error occurred while fetching messages.*/
     MCOErrorFetch,
-    // IMAP: Error occurred while IDLing.
+    /** IMAP: Error occurred while IDLing.*/
     MCOErrorIdle,
-    // IMAP: Error occurred while sending/getting identity.
+    /** IMAP: Error occurred while sending/getting identity.*/
     MCOErrorIdentity,
-    // IMAP: Error occurred while getting namespace.
+    /** IMAP: Error occurred while getting namespace.*/
     MCOErrorNamespace,
-    // IMAP: Error occurred while storing flags.
+    /** IMAP: Error occurred while storing flags.*/
     MCOErrorStore,
-    // IMAP: Error wile getting capabilities.
+    /** IMAP: Error wile getting capabilities.*/
     MCOErrorCapability,
-    // STARTTLS is not available.
+    /** STARTTLS is not available.*/
     MCOErrorStartTLSNotAvailable,
-    // SMTP: Illegal attachment: certain kind of attachment cannot be sent.
+    /** SMTP: Illegal attachment: certain kind of attachment cannot be sent.*/
     MCOErrorSendMessageIllegalAttachment,
-    // SMTP: Storage limit: message is probably too big.
+    /** SMTP: Storage limit: message is probably too big.*/
     MCOErrorStorageLimit,
-    // SMTP: Sending message is not allowed.
+    /** SMTP: Sending message is not allowed.*/
     MCOErrorSendMessageNotAllowed,
-    // SMTP: Specific to hotmail. Needs to connect to webmail.
+    /** SMTP: Specific to hotmail. Needs to connect to webmail.*/
     MCOErrorNeedsConnectToWebmail,
-    // SMTP: Error while sending message.
+    /** SMTP: Error while sending message.*/
     MCOErrorSendMessage,
-    // SMTP: Authentication required.
+    /** SMTP: Authentication required.*/
     MCOErrorAuthenticationRequired,
-    // POP: Error occurred while fetching message list.
+    /** POP: Error occurred while fetching message list.*/
     MCOErrorFetchMessageList,
-    // POP: Error occurred while deleting message.
+    /** POP: Error occurred while deleting message.*/
     MCOErrorDeleteMessage,
-    // SMTP: Error while checking account.
+    /** SMTP: Error while checking account.*/
     MCOErrorInvalidAccount,
 } MCOErrorCode;
 
diff --git a/src/objc/abstract/MCOHTMLRendererDelegate.h b/src/objc/abstract/MCOHTMLRendererDelegate.h
index dae1425a..2c153ffb 100644
--- a/src/objc/abstract/MCOHTMLRendererDelegate.h
+++ b/src/objc/abstract/MCOHTMLRendererDelegate.h
@@ -12,13 +12,16 @@
 
 #import <Foundation/Foundation.h>
 
-// This delegate protocol is used to help rendering of the message.
-//
-// It will be used for the following methods.
-//
-// -[MCOMessageParser htmlRenderingWithDelegate:],
-// -[MCOMessageBuilder htmlRenderingWithDelegate:]
-// -[MCOIMAPMessage htmlRenderingWithFolder:delegate:]
+/** This delegate protocol is used to help rendering of the message.
+
+ It will be used for the following methods.
+
+ [MCOMessageParser htmlRenderingWithDelegate:],
+
+ [MCOMessageBuilder htmlRenderingWithDelegate:]
+
+ -[MCOIMAPMessage htmlRenderingWithFolder:delegate:]
+*/
 
 @class MCOAbstractPart;
 @class MCOAbstractMessage;
@@ -27,67 +30,71 @@
 
 @protocol MCOHTMLRendererDelegate <NSObject>
 
-// All methods are optional.
+/** All methods are optional.*/
 @optional
 
-// This delegate method should return YES if it can render a preview of the attachment as an image.
-// part is always a single part.
-// If the attachment can be previewed, it will be rendered using the image template.
-// If not, the attachment template will be used.
+/** This delegate method should return YES if it can render a preview of the attachment as an image.
+ part is always a single part.
+
+If the attachment can be previewed, it will be rendered using the image template.
+If not, the attachment template will be used.*/
 - (BOOL) MCOAbstractMessage:(MCOAbstractMessage *)msg canPreviewPart:(MCOAbstractPart *)part;
 
-// This delegate method should return YES if the part should be rendered.
+/** This delegate method should return YES if the part should be rendered.*/
 - (BOOL) MCOAbstractMessage:(MCOAbstractMessage *)msg shouldShowPart:(MCOAbstractPart *)part;
 
-// This delegate method returns the values to be applied to the template for the given header.
-// See the content of MCHTMLRendererCallback.cpp for the default values of the header.
+/** This delegate method returns the values to be applied to the template for the given header.
+ See the content of MCHTMLRendererCallback.cpp for the default values of the header.*/
 - (NSDictionary *) MCOAbstractMessage:(MCOAbstractMessage *)msg templateValuesForHeader:(MCOMessageHeader *)header;
 
-// This delegate method returns the values to be applied to the template for the given attachment.
-// See the content of MCHTMLRendererCallback.cpp for the default values of the attachment.
+/** This delegate method returns the values to be applied to the template for the given attachment.
+ See the content of MCHTMLRendererCallback.cpp for the default values of the attachment.*/
 - (NSDictionary *) MCOAbstractMessage:(MCOAbstractMessage *)msg templateValuesForPart:(MCOAbstractPart *)part;
 
-// The following methods returns templates. They will match the syntax of ctemplate.
-// See https://code.google.com/p/ctemplate/
+/** @name Template Methods 
+ The following methods returns templates. They will match the syntax of ctemplate.
+ See https://code.google.com/p/ctemplate/ */
 
-// This delegate method returns the template for the main header of the message.
-// See the content of MCHTMLRendererCallback.cpp for the default values of the template.
+/** This delegate method returns the template for the main header of the message.
+ See the content of MCHTMLRendererCallback.cpp for the default values of the template.*/
 - (NSString *) MCOAbstractMessage:(MCOAbstractMessage *)msg templateForMainHeader:(MCOMessageHeader *)header;
 
-// This delegate method returns the template an image attachment.
+/** This delegate method returns the template an image attachment.*/
 - (NSString *) MCOAbstractMessage:(MCOAbstractMessage *)msg templateForImage:(MCOAbstractPart *)header;
 
-// This delegate method returns the template attachment other than images.
-// See the content of MCHTMLRendererCallback.cpp for the default values of the template.
+/** This delegate method returns the template attachment other than images.
+ See the content of MCHTMLRendererCallback.cpp for the default values of the template.*/
 - (NSString *) MCOAbstractMessage:(MCOAbstractMessage *)msg templateForAttachment:(MCOAbstractPart *)part;
 
-// This delegate method returns the template of the main message.
-// It should include HEADER and a BODY values.
-// See the content of MCHTMLRendererCallback.cpp for the default values of the template.
+/** This delegate method returns the template of the main message.
+ It should include HEADER and a BODY values.
+ See the content of MCHTMLRendererCallback.cpp for the default values of the template.*/
 - (NSString *) MCOAbstractMessage_templateForMessage:(MCOAbstractMessage *)msg;
 
-// This delegate method returns the template of an embedded message (included as attachment).
-// It should include HEADER and a BODY values.
-// See the content of MCHTMLRendererCallback.cpp for the default values of the template.
+/** This delegate method returns the template of an embedded message (included as attachment).
+ It should include HEADER and a BODY values.
+ See the content of MCHTMLRendererCallback.cpp for the default values of the template.*/
 - (NSString *) MCOAbstractMessage:(MCOAbstractMessage *)msg templateForEmbeddedMessage:(MCOAbstractMessagePart *)part;
 
-// This delegate method returns the template for the header of an embedded message.
-// See the content of MCHTMLRendererCallback.cpp for the default values of the template.
+/** This delegate method returns the template for the header of an embedded message.
+ See the content of MCHTMLRendererCallback.cpp for the default values of the template.*/
 - (NSString *) MCOAbstractMessage:(MCOAbstractMessage *)msg templateForEmbeddedMessageHeader:(MCOMessageHeader *)header;
 
-// This delegate method returns the separator between the text of the message and the attachments.
-// This delegate method returns the template for the header of an embedded message.
+/** This delegate method returns the separator between the text of the message and the attachments.
+ This delegate method returns the template for the header of an embedded message.*/
 - (NSString *) MCOAbstractMessage_templateForAttachmentSeparator:(MCOAbstractMessage *)msg;
 
-// The following methods will filter the HTML content and may apply some filters to
-// change how to display the message.
+/** @name Filters
+   
+ The following methods will filter the HTML content and may apply some filters to
+ change how to display the message.*/
 
-// This delegate method will apply the filter to HTML rendered content of a given text part.
-// For example, it could filter the CSS content.
+/** This delegate method will apply the filter to HTML rendered content of a given text part.
+ For example, it could filter the CSS content.*/
 - (NSString *) MCOAbstractMessage:(MCOAbstractMessage *)msg filterHTMLForPart:(NSString *)html;
 
-// This delegate method will apply a filter to the whole HTML content.
-// For example, it could collapse the quoted messages.
+/** This delegate method will apply a filter to the whole HTML content.
+ For example, it could collapse the quoted messages.*/
 - (NSString *) MCOAbstractMessage:(MCOAbstractMessage *)msg filterHTMLForMessage:(NSString *)html;
 
 @end
diff --git a/src/objc/abstract/MCOHTMLRendererIMAPDelegate.h b/src/objc/abstract/MCOHTMLRendererIMAPDelegate.h
index 562256c3..aadbb350 100644
--- a/src/objc/abstract/MCOHTMLRendererIMAPDelegate.h
+++ b/src/objc/abstract/MCOHTMLRendererIMAPDelegate.h
@@ -12,31 +12,39 @@
 
 #import <MailCore/MCOHTMLRendererDelegate.h>
 
-// This delegate protocol is used to fetch the content of the part of the message when the HTML render needs them.
-// It will help fetch the minimal amount of information from the message required to render the HTML.
-//
-// It will be used for the following method.
-//
-// -[MCOIMAPMessage htmlRenderingWithFolder:delegate:]
+/**
+ This delegate protocol is used to fetch the content of the part of the message when the HTML render needs them.
+ It will help fetch the minimal amount of information from the message required to render the HTML.
+
+ It will be used for the following method.
+
+ [MCOIMAPMessage htmlRenderingWithFolder:delegate:]
+*/
 
 @class MCOIMAPPart;
 
 @protocol MCOHTMLRendererIMAPDelegate <MCOHTMLRendererDelegate>
 
-// All methods are optional.
+/** All methods are optional.*/
 @optional
 
-// The delegate method returns NULL if the delegate have not fetch the part yet. The opportunity can also be used to
-// start fetching the attachment.
-// It will return the data synchronously if it has already fetched it.
+/** 
+ The delegate method returns NULL if the delegate have not fetch the part yet. The opportunity can also be used to
+ start fetching the attachment.
+ It will return the data synchronously if it has already fetched it.
+*/
 - (NSData *) MCOAbstractMessage:(MCOAbstractMessage *)msg dataForIMAPPart:(MCOIMAPPart *)part folder:(NSString *)folder;
 
-// The delegate method will notify the delegate to start fetching the given part.
-// It will be used to render an attachment that cannot be previewed.
+/**
+ The delegate method will notify the delegate to start fetching the given part.
+ It will be used to render an attachment that cannot be previewed.
+*/
 - (void) MCOAbstractMessage:(MCOAbstractMessage *)msg prefetchAttachmentIMAPPart:(MCOIMAPPart *)part folder:(NSString *)folder;
 
-// The delegate method will notify the delegate to start fetching the given part.
-// It will be used to render an attachment that can be previewed.
+/**
+ The delegate method will notify the delegate to start fetching the given part.
+ It will be used to render an attachment that can be previewed.
+*/
 - (void) MCOAbstractMessage:(MCOAbstractMessage *)msg prefetchImageIMAPPart:(MCOIMAPPart *)part folder:(NSString *)folder;
 
 @end
diff --git a/src/objc/abstract/MCOMessageHeader.h b/src/objc/abstract/MCOMessageHeader.h
index 899f8d38..6e8eb9bf 100644
--- a/src/objc/abstract/MCOMessageHeader.h
+++ b/src/objc/abstract/MCOMessageHeader.h
@@ -12,67 +12,67 @@
 
 #import <Foundation/Foundation.h>
 
-// This class implements common fields of a message header.
+/** This class implements common fields of a message header.*/
 
 @class MCOAddress;
 
 @interface MCOMessageHeader : NSObject <NSCopying>
 
-// Message-ID field.
+/** Message-ID field.*/
 @property (nonatomic, copy) NSString * messageID;
 
-// References field. It's an array of message-ids.
+/** References field. It's an array of message-ids.*/
 @property (nonatomic, copy) NSArray * /* NSString */ references;
 
-// In-Reply-To field. It's an array of message-ids.
+/** In-Reply-To field. It's an array of message-ids.*/
 @property (nonatomic, copy) NSArray * /* NSString */ inReplyTo;
 
-// Date field: sent date of the message.
+/** Date field: sent date of the message.*/
 @property (nonatomic, strong) NSDate * date;
 
-// Received date: received date of the message.
+/** Received date: received date of the message.*/
 @property (nonatomic, strong) NSDate * receivedDate;
 
-// Sender field.
+/** Sender field.*/
 @property (nonatomic, copy) MCOAddress * sender;
 
-// From field: address of the sender of the message.
+/** From field: address of the sender of the message.*/
 @property (nonatomic, copy) MCOAddress * from;
 
-// To field: recipient of the message. It's an array of MCOAddress.
+/** To field: recipient of the message. It's an array of MCOAddress.*/
 @property (nonatomic, copy) NSArray * /* MCOAddress */ to;
 
-// Cc field: cc recipient of the message. It's an array of MCOAddress.
+/** Cc field: cc recipient of the message. It's an array of MCOAddress.*/
 @property (nonatomic, copy) NSArray * /* MCOAddress */ cc;
 
-// Bcc field: bcc recipient of the message. It's an array of MCOAddress.
+/** Bcc field: bcc recipient of the message. It's an array of MCOAddress.*/
 @property (nonatomic, copy) NSArray * /* MCOAddress */ bcc;
 
-// Reply-To field. It's an array of MCOAddress.
+/** Reply-To field. It's an array of MCOAddress.*/
 @property (nonatomic, copy) NSArray * /* MCOAddress */ replyTo;
 
-// Subject of the message.
+/** Subject of the message.*/
 @property (nonatomic, copy) NSString * subject;
 
-// User-Agent.
+/** User-Agent.*/
 @property (nonatomic, copy) NSString * userAgent;
 
-// Extracted subject (also remove square brackets).
+/** Extracted subject (also remove square brackets).*/
 - (NSString *) extractedSubject;
 
-// Extracted subject (don't remove square brackets).
+/** Extracted subject (don't remove square brackets).*/
 - (NSString *) partialExtractedSubject;
 
-// Fill the header using the given RFC 822 data.
+/** Fill the header using the given RFC 822 data.*/
 - (void) importHeadersData:(NSData *)data;
 
-// Returns a header that can be used as a base for a reply message.
+/** Returns a header that can be used as a base for a reply message.*/
 - (MCOMessageHeader *) replyHeaderWithExcludedRecipients:(NSArray *)excludedRecipients;
 
-// Returns a header that can be used as a base for a reply all message.
+/** Returns a header that can be used as a base for a reply all message.*/
 - (MCOMessageHeader *) replyAllHeaderWithExcludedRecipients:(NSArray *)excludedRecipients;
 
-// Returns a header that can be used as a base for a forward message.
+/** Returns a header that can be used as a base for a forward message.*/
 - (MCOMessageHeader *) forwardHeader;
 
 @end
diff --git a/src/objc/imap/MCOIMAPAppendMessageOperation.h b/src/objc/imap/MCOIMAPAppendMessageOperation.h
index 95f29f5d..c23d79a1 100644
--- a/src/objc/imap/MCOIMAPAppendMessageOperation.h
+++ b/src/objc/imap/MCOIMAPAppendMessageOperation.h
@@ -10,22 +10,29 @@
 
 #define __MAILCORE_MCOIMAPAPPENDMESSAGEOPERATION_H_
 
-// This class implements an operation that adds a message to a folder.
+/** 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.
+/** 
+ This block will be called as bytes are sent
+*/
 @property (nonatomic, copy) MCOIMAPBaseOperationProgressBlock progress;
 
-// 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.
+/** 
+ Starts the asynchronous append operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `createdUID` will be the value of the 
+   UID of  the created message if 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 84e03892..f5bf88af 100644
--- a/src/objc/imap/MCOIMAPBaseOperation.h
+++ b/src/objc/imap/MCOIMAPBaseOperation.h
@@ -10,7 +10,7 @@
 
 #define __MAILCORE_MCOIMAPBASEOPERATION_H_
 
-// It's a generic IMAP operation with progress.
+/** Represents a generic IMAP operation with methods that are called with progress updates */
 
 #import <MailCore/MCOOperation.h>
 
@@ -19,13 +19,21 @@ typedef void (^MCOIMAPBaseOperationItemProgressBlock)(unsigned int current);
 
 @interface MCOIMAPBaseOperation : MCOOperation
 
-// 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;
+/* Can be overriden by subclasses */
+
+/* 
+ Will be called when a sending or receiving the contents of a message 
+ @param current The number of bytes sent or received
+ @param maximum The total number of bytes expected
+*/
+- (void)bodyProgress:(unsigned int)current maximum:(unsigned int)maximum;
+
+/*
+ Will be called when a new item is received in a list of items, like for example a message list
+ @param current The number of items downloaded
+ @param maximum The total number of items expected
+*/
+- (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 38166e0b..29b0d3be 100644
--- a/src/objc/imap/MCOIMAPCapabilityOperation.h
+++ b/src/objc/imap/MCOIMAPCapabilityOperation.h
@@ -10,7 +10,10 @@
 
 #define __MAILCORE_MCOIMAPCAPBILITYOPERATION_H_
 
-// This class implements an operation to query capabilities.
+/** 
+ This class implements an operation to query for IMAP capabilities, 
+ like for example the extensions UIDPLUS, IDLE, NAMESPACE, ... etc
+*/
 
 #import <MailCore/MCOIMAPBaseOperation.h>
 
@@ -18,11 +21,18 @@
 
 @interface MCOIMAPCapabilityOperation : MCOIMAPBaseOperation
 
-// 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.
+
+/** 
+ Starts the asynchronous capabilities operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `capabilities` will contain a set of IMAP capabilities.
+   See `MCOConstants.h` under `MCOIMAPCapability` for a list of possible values.
+ 
+ - On failure, `error` will be set with `MCOErrorDomain` as domain and an 
+   error code available in MCOConstants.h, `capabilities` 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 0fb3c5ad..c916e1d7 100644
--- a/src/objc/imap/MCOIMAPCopyMessagesOperation.h
+++ b/src/objc/imap/MCOIMAPCopyMessagesOperation.h
@@ -12,17 +12,24 @@
 
 #define __MAILCORE_MCOCOPYMESSAGESOPERATION_H_
 
-// This class implements an operation to copy messages.
+/** Implements an operation for copying messages between folders */
 
 @class MCOIndexSet;
 
 @interface MCOIMAPCopyMessagesOperation : MCOIMAPBaseOperation
 
-// 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.
+/** 
+ Starts the asynchronous copy operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `destUids` will contain the UIDs of the messages created
+   in the destination folder. If the server doesn't support UIDPLUS then `destUids` will be nil.
+ 
+ - On failure, `error` will be set with `MCOErrorDomain` as domain and an 
+   error code available in `MCOConstants.h`, `destUids` 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 f43425bb..1886981a 100644
--- a/src/objc/imap/MCOIMAPFetchContentOperation.h
+++ b/src/objc/imap/MCOIMAPFetchContentOperation.h
@@ -10,22 +10,32 @@
 
 #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.
+/** 
+ 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.
+/** 
+ This block will be called as bytes are received from the network
+*/
 @property (nonatomic, copy) MCOIMAPBaseOperationProgressBlock progress;
 
-// 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.
+/** 
+ Starts the asynchronous fetch operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `data` will contain the requested data
+ 
+ - 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 90feb870..e4352bd2 100644
--- a/src/objc/imap/MCOIMAPFetchFoldersOperation.h
+++ b/src/objc/imap/MCOIMAPFetchFoldersOperation.h
@@ -10,16 +10,22 @@
 
 #define __MAILCORE_MCOIMAPFETCHFOLDERSOPERATION_H_
 
-// This class implements an operation to fetch a list of folders.
+/** This class implements an operation to fetch a list of folders. */
 
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @interface MCOIMAPFetchFoldersOperation : MCOIMAPBaseOperation
 
-// 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.
+/** 
+ Starts the asynchronous fetch operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `folders` will contain 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
diff --git a/src/objc/imap/MCOIMAPFetchMessagesOperation.h b/src/objc/imap/MCOIMAPFetchMessagesOperation.h
index 32a3a451..659d9bca 100644
--- a/src/objc/imap/MCOIMAPFetchMessagesOperation.h
+++ b/src/objc/imap/MCOIMAPFetchMessagesOperation.h
@@ -13,21 +13,28 @@
 #import <MailCore/MCOIMAPBaseOperation.h>
 #import <MailCore/MCOConstants.h>
 
-// This class implements an operation to fetch a list of messages.
+/** This class implements an operation to fetch a list of messages from a folder */
 
 @class MCOIndexSet;
 
 @interface MCOIMAPFetchMessagesOperation : MCOIMAPBaseOperation
 
-// This block will be called each time a new message information will be downloaded.
+/** This block will be called each time a new message is downloaded. */
 @property (nonatomic, copy) MCOIMAPBaseOperationItemProgressBlock progress;
 
-// 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.
+/** 
+ Starts the asynchronous fetch operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `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
+ 
+ - On failure, `error` will be set with `MCOErrorDomain` as domain and an 
+   error code available in `MCOConstants.h`, `messages` and `vanishedMessages` will be nil
+
+   If you are not supporting QRESYNC you can safely ignore `vanishedMessages`.
+*/
 - (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 b7e5fb64..ce845f5e 100644
--- a/src/objc/imap/MCOIMAPFetchNamespaceOperation.h
+++ b/src/objc/imap/MCOIMAPFetchNamespaceOperation.h
@@ -10,23 +10,28 @@
 
 #define __MAILCORE_MCOIMAPFETCHNAMESPACEOPERATION_H_
 
-// This class implements an operation to fetch namespaces.
+/** This class implements an operation to fetch any IMAP namespaces. */
 
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @interface MCOIMAPFetchNamespaceOperation : MCOIMAPBaseOperation
 
-// 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.
+/** 
+ Starts the asynchronous namespace fetch operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `namespaces` will contain these keys: 
+
+     - `MCOIMAPNamespacePersonal` for personal namespaces,
+     - `MCOIMAPNamespaceOther` for other namespaces,
+     - `MCOIMAPNamespaceShared` for shared namespaces.
+
+   Values of the dictionary 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 03858fc5..8688ef5b 100644
--- a/src/objc/imap/MCOIMAPFolder.h
+++ b/src/objc/imap/MCOIMAPFolder.h
@@ -10,20 +10,23 @@
 
 #define __MAILCORE_MCOIMAPFOLDER_H_
 
-// This class implements an IMAP folder.
+/** This class represents an IMAP folder */
 
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOConstants.h>
 
 @interface MCOIMAPFolder : NSObject <NSCopying>
 
-// It's the path of the folder.
+/** The folder's path, like for example INBOX.Archive */
 @property (nonatomic, copy) NSString * path;
 
-// It's the delimiter for each component of the path.
+/** It's the delimiter for each component of the path. Commonly . or / */
 @property (nonatomic, assign) char delimiter;
 
-// It's the flags of the folder. See MCOIMAPFolderFlag.
+/** 
+ Any flags the folder may have, like if the folder is for Drafts, Spam, Junk, etc. Or
+ it could be marked with metadata like that it has no children.
+*/
 @property (nonatomic, assign) MCOIMAPFolderFlag flags;
 
 @end
diff --git a/src/objc/imap/MCOIMAPFolderInfo.h b/src/objc/imap/MCOIMAPFolderInfo.h
index dfff3f9f..949e900e 100644
--- a/src/objc/imap/MCOIMAPFolderInfo.h
+++ b/src/objc/imap/MCOIMAPFolderInfo.h
@@ -12,23 +12,23 @@
 
 #import <Foundation/Foundation.h>
 
-// This class is a cluster for some folder information.
+/* This class holds IMAP folder metadata */
 
 @interface MCOIMAPFolderInfo : NSObject
 
-// Returns a new allocated folder info.
+/** Create an empty instance */
 + (MCOIMAPFolderInfo *) info;
 
-// UIDNEXT value.
+/** The folder's IMAP UIDNEXT value. Used to determine the uid for the next received message. */
 @property (nonatomic, assign) uint32_t uidNext;
 
-// UIDVALIDITY value.
+/** The folders IMAP UIDVALIDITY value. Must be used to determine if the server has changed assigned UIDs */
 @property (nonatomic, assign) uint32_t uidValidity;
 
-// MODSEQ value.
+/** An advanced value used for doing quick flag syncs if the server supports it. The MODSEQ value. */
 @property (nonatomic, assign) uint64_t modSequenceValue;
 
-// number of messages.
+/** Total number of messages in the folder */
 @property (nonatomic, assign) int messageCount;
 
 // first uid of the unseen messages.
diff --git a/src/objc/imap/MCOIMAPFolderInfoOperation.h b/src/objc/imap/MCOIMAPFolderInfoOperation.h
index 73101641..d26e47a8 100644
--- a/src/objc/imap/MCOIMAPFolderInfoOperation.h
+++ b/src/objc/imap/MCOIMAPFolderInfoOperation.h
@@ -12,17 +12,26 @@
 
 #import <MailCore/MCOIMAPBaseOperation.h>
 
-// This class implements the operation that will fetch some folder information
-// (uidNext uidValidity, modSequenceValue, messageCount).
+/**
+ The class is used to get folder metadata (like UIDVALIDITY, UIDNEXT, etc).
+ @see MCOIMAPFolderInfo
+*/
 
 @class MCOIMAPFolderInfo;
 
 @interface MCOIMAPFolderInfoOperation : MCOIMAPBaseOperation
 
-// 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.
+/** 
+ Starts the asynchronous operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `info` will contain the folder metadata
+ 
+ - 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
diff --git a/src/objc/imap/MCOIMAPIdentityOperation.h b/src/objc/imap/MCOIMAPIdentityOperation.h
index 0a32892c..d0d5f27b 100644
--- a/src/objc/imap/MCOIMAPIdentityOperation.h
+++ b/src/objc/imap/MCOIMAPIdentityOperation.h
@@ -10,17 +10,28 @@
 
 #define __MAILCORE_MCOIMAPIDENTITYOPERATION_H_
 
-// This class implements an operation to get/send identity.
+/** 
+ This class implements an operation to get the servers identification info or
+ to send the clients identification info. Useful for bug reports and usage
+ statistics. 
+ @warn Not all servers support this.
+*/
 
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @interface MCOIMAPIdentityOperation : MCOIMAPBaseOperation
 
-// 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.
+/** 
+ Starts the asynchronous identity operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `serverIdentity` will contain identifying server information.
+   See [RFC2971](http://tools.ietf.org/html/rfc2971) for commons dictionary keys.
+ 
+ - 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 2da19d19..01b4f443 100644
--- a/src/objc/imap/MCOIMAPIdleOperation.h
+++ b/src/objc/imap/MCOIMAPIdleOperation.h
@@ -10,18 +10,29 @@
 
 #define __MAILCORE_MCOIMAPIDLEOPERATION_H_
 
-// This class implements an idle operation.
+/** 
+ This class implements an IMAP IDLE. IDLE is used to keep a connection
+ open with the server so that new messages can be pushed to the client.
+ See [RFC2177](http://tools.ietf.org/html/rfc2177)
+*/
 
 #import <MailCore/MCOIMAPBaseOperation.h>
 
 @interface MCOIMAPIdleOperation : MCOIMAPBaseOperation
 
-// Interrupts the IDLE operation.
+/** Stop the current IDLE session */
 - (void) interruptIdle;
 
-// 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.
+/** 
+ Starts IDLE
+
+ @param completionBlock Called when the IDLE times out, errors out or detects a change
+
+ - On success `error` will be nil
+ 
+ - 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 f0a1e0ec..81dfa9f7 100644
--- a/src/objc/imap/MCOIMAPMessage.h
+++ b/src/objc/imap/MCOIMAPMessage.h
@@ -10,14 +10,19 @@
 
 #define __MAILCORE_MCOIMAPMESSAGE_H_
 
-// This class implements an IMAP message.
-// If you fetched the MIME structure of the message, you can fetch
-// efficiently the content of the message by fetching only the parts
-// that you need to show it.
-// For example, you could fetch only the text parts to show the summary
-// of the message, using -[MCOIMAPSession fetchMessageAttachmentByUIDOperationWithFolder:uid:partID:encoding:]
-// You can also decide to fetch entirely the message using
-// -[MCOIMAPSession fetchMessageByUIDOperationWithFolder:uid:]
+/** 
+ This represents an IMAP message.
+
+ If you fetched the MIME structure of the message, you can fetch
+ efficiently the content of the message by fetching only the parts
+ that you need to show it.
+
+ For example, you could fetch only the text parts to show the summary
+ of the message, using [MCOIMAPSession fetchMessageAttachmentByUIDOperationWithFolder:uid:partID:encoding:]
+
+ You can also decide to fetch entirely the message using
+ [MCOIMAPSession fetchMessageByUIDOperationWithFolder:uid:]
+*/
 
 #import <MailCore/MCOAbstractMessage.h>
 #import <MailCore/MCOConstants.h>
@@ -26,32 +31,36 @@
 
 @interface MCOIMAPMessage : MCOAbstractMessage <NSCopying>
 
-// It's the UID of the message.
+/** IMAP UID of the message. */
 @property (nonatomic, assign) uint32_t uid;
 
-// It's the flags of the message.
+/** Flags of the message, like if it is deleted, read, starred etc */
 @property (nonatomic, assign) MCOMessageFlag flags;
 
-// It's the flags of the message fetched from the server.
+/** The contents of the message flags when it was fetched from the server */
 @property (nonatomic, assign) MCOMessageFlag originalFlags;
 
-// It's the last modification sequence value of the message synced from the server.
+/** It's the last modification sequence value of the message synced from the server. See RFC4551 */
 @property (nonatomic, assign) uint64_t modSeqValue;
 
-// It's the main MIME part of the message.
+/** Main MIME part of the message */
 @property (nonatomic, retain) MCOAbstractPart * mainPart;
 
-// It's the Gmail labels of the message.
+/** Any 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
+/**
+ Returns the part with the given part identifier.
+ @param partID A part identifier looks like 1.2.1
+*/
 - (MCOAbstractPart *) partForPartID:(NSString *)partID;
 
-// 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.
+/**
+ 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 take place.
+*/
 - (NSString *) htmlRenderingWithFolder:(NSString *)folder
                               delegate:(id <MCOHTMLRendererIMAPDelegate>)delegate;
 
diff --git a/src/objc/imap/MCOIMAPMessagePart.h b/src/objc/imap/MCOIMAPMessagePart.h
index 22ce8a50..b602d93a 100644
--- a/src/objc/imap/MCOIMAPMessagePart.h
+++ b/src/objc/imap/MCOIMAPMessagePart.h
@@ -10,14 +10,13 @@
 
 #define __MAILCORE_MCOIMAPMESSAGEPART_H_
 
-// This class implements a message part.
+/** Represents a message part. */
 
 #import <MailCore/MCOAbstractMessagePart.h>
 
 @interface MCOIMAPMessagePart : MCOAbstractMessagePart <NSCopying>
 
-// It's the part identifier.
-// A part identifier looks like 1.2.1
+/** A part identifier is of the form 1.2.1*/
 @property (nonatomic, copy) NSString * partID;
 
 @end
diff --git a/src/objc/imap/MCOIMAPMultipart.h b/src/objc/imap/MCOIMAPMultipart.h
index d178a2ce..0e0bb0eb 100644
--- a/src/objc/imap/MCOIMAPMultipart.h
+++ b/src/objc/imap/MCOIMAPMultipart.h
@@ -10,14 +10,13 @@
 
 #define __MAILCORE_MCOIMAPMULTIPART_H_
 
-// This class implements a multipart.
+/** Represents the a multipart retrieved from IMAP */
 
 #import <MailCore/MCOAbstractMultipart.h>
 
 @interface MCOIMAPMultipart : MCOAbstractMultipart <NSCopying>
 
-// It's the part identifier.
-// A part identifier looks like 1.2.1
+/** 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 392a3d1b..f3373c64 100644
--- a/src/objc/imap/MCOIMAPNamespace.h
+++ b/src/objc/imap/MCOIMAPNamespace.h
@@ -10,7 +10,7 @@
 
 #define __MAILCORE_MCOIMAPNAMESPACE_H_
 
-// This class implements an IMAP namespace.
+/** Represents an IMAP namespace */
 
 #import <Foundation/Foundation.h>
 
@@ -18,31 +18,36 @@
 
 @interface MCOIMAPNamespace : NSObject <NSCopying>
 
-// Returns a simple namespace with only an item.
-// This item will have the given prefix and the given path delimiter.
+/**
+ Returns a simple namespace with only one item.
+*/
 + (MCOIMAPNamespace *) namespaceWithPrefix:(NSString *)prefix delimiter:(char)delimiter;
 
-// Returns the prefix of the main item of this namespace.
+/** Returns the prefix of the main item of this namespace. */
 - (NSString *) mainPrefix;
 
-// Returns the path delimiter of the main item of this namespace.
+/** Returns the path delimiter of the main item of this namespace */
 - (char) mainDelimiter;
 
-// Returns the list of prefixes of this namespace.
+/** 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.
+/**
+ 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.
+/**
+ 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.
+/** Returns the components given a folder path. */
 - (NSArray *) componentsFromPath:(NSString *)path;
 
-// Returns YES if the namespace contains the given folder 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 6171b464..b23d0dfc 100644
--- a/src/objc/imap/MCOIMAPNamespaceItem.h
+++ b/src/objc/imap/MCOIMAPNamespaceItem.h
@@ -10,25 +10,25 @@
 
 #define __MAILCORE_MCOIMAPNAMESPACEITEM_H_
 
-// This class implements an IMAP namespace item.
+/** Represents a namespace item */
 
 #import <Foundation/Foundation.h>
 
 @interface MCOIMAPNamespaceItem : NSObject <NSCopying>
 
-// This is the prefix for this namespace item.
+/** This is the prefix for this namespace item */
 @property (nonatomic, copy) NSString * prefix;
 
-// This is the delimiter of the path for this namespace item.
+/** 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.
+/** 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.
+/** Returns components for the given path in the context of this namespace */
 - (NSArray *) componentsForPath:(NSString *)path;
 
-// Returns YES if the namespace contains this folder 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 74aba70a..b8ee37e4 100644
--- a/src/objc/imap/MCOIMAPOperation.h
+++ b/src/objc/imap/MCOIMAPOperation.h
@@ -10,15 +10,22 @@
 
 #define __MAILCORE_MCOIMAPOPERATION_H_
 
-// This class implements a generic IMAP operation.
+/** This class implements a generic IMAP operation */
 
 #import <MailCore/MCOOperation.h>
 
 @interface MCOIMAPOperation : MCOOperation
 
-// 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.
+/** 
+ Starts the asynchronous append operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil
+ 
+ - 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 58bdfd2d..029135bf 100644
--- a/src/objc/imap/MCOIMAPPart.h
+++ b/src/objc/imap/MCOIMAPPart.h
@@ -14,20 +14,23 @@
 
 #import <MailCore/MCOConstants.h>
 
+/** Represents a single IMAP message part */
+
 @interface MCOIMAPPart : MCOAbstractPart <NSCopying>
 
-// It's the part identifier.
-// A part identifier looks like 1.2.1
+/** A part identifier looks like 1.2.1 */
 @property (nonatomic, copy) NSString * partID;
 
-// It's the size of the single part.
+/** The size of the single part in bytes */
 @property (nonatomic, nonatomic) unsigned int size;
 
-// It's the encoding of the single part.
+/** 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.
+/**
+ 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 d0c439e9..17a7656a 100644
--- a/src/objc/imap/MCOIMAPSearchExpression.h
+++ b/src/objc/imap/MCOIMAPSearchExpression.h
@@ -10,64 +10,77 @@
 
 #define __MAILCORE_MCOIMAPSEARCHEXPRESSION_H_
 
-// This class implements a search expression.
+/** Used to construct an IMAP search query */
 
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOConstants.h>
 
 @interface MCOIMAPSearchExpression : NSObject
+/**
+ Creates a search expression that matches the sender of an email.
 
-// Creates a search expression that matches the sender of an email.
-//
-// Example:
-// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"]
-//
+ 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"]
-//
+/**
+ 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"]
-//
+/*
+ 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"]
-//
+/**
+ 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"]
-//
+/**
+ 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];
-//
+/**
+ 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.
 
-// 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];
-//
+ 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 25795cfb..a178984d 100644
--- a/src/objc/imap/MCOIMAPSearchOperation.h
+++ b/src/objc/imap/MCOIMAPSearchOperation.h
@@ -10,7 +10,7 @@
 
 #define __MAILCORE_MCOSEARCHOPERATION_H_
 
-// This class implements a search operation.
+/** This class runs an IMAP search operation */
 
 #import <MailCore/MCOIMAPBaseOperation.h>
 
@@ -18,10 +18,17 @@
 
 @interface MCOIMAPSearchOperation : MCOIMAPBaseOperation
 
-// 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.
+/** 
+ Starts the asynchronous search operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `searchResults` will contain the UIDs of any matching 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 344550b5..eec0d152 100644
--- a/src/objc/imap/MCOIMAPSession.h
+++ b/src/objc/imap/MCOIMAPSession.h
@@ -29,484 +29,462 @@
 @class MCOIMAPIdentityOperation;
 @class MCOIMAPCapabilityOperation;
 
-// This class implements asynchronous IMAP protocol.
+/**
+ This is the main IMAP class from which all operations are created 
+
+ After calling a method that returns an operation you must call start: on the instance
+ to begin the operation.
+*/
 
 @interface MCOIMAPSession : NSObject
 
-// This is the hostname of the POP3 server to connect to.
+/** This is the hostname of the IMAP server to connect to. */
 @property (nonatomic, strong) NSString *hostname;
 
-// This is the port of the IMAP server to connect to.
+/** This is the port of the IMAP server to connect to. */
 @property (nonatomic, assign) unsigned int port;
 
-// This is the username of the account.
+/** This is the username of the account. */
 @property (nonatomic, strong) NSString *username;
 
-// This is the password of the account.
+/** 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.
+/** 
+ This is the authentication type to use to connect.
+ `MCOAuthTypeSASLNone` means that it uses the clear-text is used (and is the default).
+ @warning *Important*: Over an encrypted connection like TLS, the password will still be secure
+*/
 @property (nonatomic, assign) MCOAuthType authType;
 
-// This is the encryption type to use.
-// See MCOConnectionType for more information.
+/**
+ This is the encryption type to use.
+ See MCOConnectionType for more information.
+*/
 @property (nonatomic, assign) MCOConnectionType connectionType;
 
-// This is the timeout of the connection.
+/** 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.
+/** 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;
+/** 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.
+/** The default delimiter for the folder paths */
 @property (nonatomic, assign) char delimiter;
 
-// The default namespace.
+/** 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.
+/**
+ When set to YES, the session is allowed open to open several connections to the same folder.
+ @warning Some older IMAP servers don't like this
+*/
 @property (nonatomic, assign) BOOL allowsFolderConcurrentAccessEnabled;
 
-// Maximum number of connections to the server allowed.
+/**
+ 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 * op = [session folderInfoOperation:@"INBOX"];
-//   [op start:^(NSError *error, MCOIMAPFolderInfo * info) {
-//        NSLog(@"UIDNEXT: %lu", (unsigned long) [info uidNext]);
-//        NSLog(@"UIDVALIDITY: %lu", (unsigned long) [info uidValidity]);
-//        NSLog(@"HIGHESTMODSEQ: %llu", (unsigned long long) [info modSequenceValue]);
-//        NSLog(@"messages count: %lu", [info messageCount]);
-//   }]];
-//
+/** @name Folder Operations */
+
+/**
+ Returns an operation that retrieves folder metadata (like UIDNext)
+
+     MCOIMAPFolderInfoOperation * op = [session folderInfoOperation:@"INBOX"];
+     [op start:^(NSError *error, MCOIMAPFolderInfo * info) {
+          NSLog(@"UIDNEXT: %lu", (unsigned long) [info uidNext]);
+          NSLog(@"UIDVALIDITY: %lu", (unsigned long) [info uidValidity]);
+          NSLog(@"HIGHESTMODSEQ: %llu", (unsigned long long) [info modSequenceValue]);
+          NSLog(@"messages count: %lu", [info messageCount]);
+     }];
+*/
+
 - (MCOIMAPFolderInfoOperation *) folderInfoOperation:(NSString *)folder;
 
-// Returns an operation to fetch subscribed folders.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIMAPFetchFoldersOperation * op = [session fetchAllFoldersOperation];
-//   [op start:^(NSError * error, NSArray * /* MCOIMAPFolder */ folders) {
-//        ...
-//   }]];
-//
+/**
+ Returns an operation that gets the list of subscribed folders.
+
+     MCOIMAPFetchFoldersOperation * op = [session fetchAllFoldersOperation];
+     [op start:^(NSError * error, NSArray * folders) {
+          ...
+     }];
+*/
 - (MCOIMAPFetchFoldersOperation *) fetchSubscribedFoldersOperation;
 
-// Returns an operation to fetch all folders.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIMAPFetchFoldersOperation * op = [session fetchAllFoldersOperation];
-//   [op start:^(NSError * error, NSArray * /* MCOIMAPFolder */ folders) {
-//        ...
-//   }]];
-//
+/**
+ Returns an operation that gets all folders
+
+     MCOIMAPFetchFoldersOperation * op = [session fetchAllFoldersOperation];
+     [op start:^(NSError * error, NSArray *folders) {
+          ...
+     }];
+*/
 - (MCOIMAPFetchFoldersOperation *) fetchAllFoldersOperation;
 
-// Returns an operation to rename a folder.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIMAPOperation * op = [session renameFolderOperation:@"my documents" otherName:@"Documents"];
-//   [op start:^(NSError * error) {
-//        ...
-//   }]];
-//
+/**
+ Creates an operation for renaming a folder
+
+     MCOIMAPOperation * op = [session renameFolderOperation:@"my documents" otherName:@"Documents"];
+     [op start:^(NSError * error) {
+        ...
+     }];
+
+*/
 - (MCOIMAPOperation *) renameFolderOperation:(NSString *)folder otherName:(NSString *)otherName;
 
-// Returns an operation to delete a folder.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIMAPOperation * op = [session deleteFolderOperation:@"holidays 2009"];
-//   [op start:^(NSError * error) {
-//        ...
-//   }]];
-//
+/**
+ Create an operation for deleting a folder
+
+     MCOIMAPOperation * op = [session deleteFolderOperation:@"holidays 2009"];
+     [op start:^(NSError * error) {
+          ...
+     }]];
+*/
 - (MCOIMAPOperation *) deleteFolderOperation:(NSString *)folder;
 
-// Returns an operation to create a folder.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIMAPOperation * op = [session createFolderOperation:@"holidays 2013"];
-//   [op start:^(NSError * error) {
-//        ...
-//   }];
-//
+/**
+ Returns an operation that creates a new folder
+
+     MCOIMAPOperation * op = [session createFolderOperation:@"holidays 2013"];
+     [op start:^(NSError * error) {
+          ...
+     }];
+*/  
 - (MCOIMAPOperation *) createFolderOperation:(NSString *)folder;
 
-// Returns an operation to subscribe a folder.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIMAPOperation * op = [session createFolderOperation:@"holidays 2013"];
-//   [op start:^(NSError * error) {
-//     if (error != nil)
-//       return;
-//     MCOIMAPOperation * op = [session subscribeFolderOperation:@"holidays 2013"] {
-//     ...
-//     }];
-//   }]];
-//
+/**
+ Returns an operation to subscribe to a folder.
+
+     MCOIMAPOperation * op = [session createFolderOperation:@"holidays 2013"];
+     [op start:^(NSError * error) {
+       if (error != nil)
+         return;
+       MCOIMAPOperation * op = [session subscribeFolderOperation:@"holidays 2013"];
+       ...
+     }];
+*/
 - (MCOIMAPOperation *) subscribeFolderOperation:(NSString *)folder;
 
-// Returns an operation to unsubscribe a folder.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIMAPOperation * op = [session unsubscribeFolderOperation:@"holidays 2009"];
-//   [op start:^(NSError * error) {
-//     if (error != nil)
-//       return;
-//     MCOIMAPOperation * op = [session deleteFolderOperation:@"holidays 2009"] {
-//     ...
-//     }];
-//   }]];
-//
+/**
+ Returns an operation to unsubscribe from a folder.
+
+     MCOIMAPOperation * op = [session unsubscribeFolderOperation:@"holidays 2009"];
+     [op start:^(NSError * error) {
+       if (error != nil)
+         return;
+       MCOIMAPOperation * op = [session deleteFolderOperation:@"holidays 2009"]
+       ...
+     }];
+*/
 - (MCOIMAPOperation *) unsubscribeFolderOperation:(NSString *)folder;
 
-// Returns an operation to add a message to a folder.
-// The operation needs to be started.
-// {
-//   ...
-//   MCOIMAPOperation * op = [session appendMessageOperationWithFolder:@"Sent Mail" messageData:rfc822Data flags:MCOMessageFlagNone];
-//   [op start:^(NSError * error, uint32_t createdUID) {
-//     if (error == nil) {
-//       NSLog(@"created message with UID %lu", (unsigned long) createdUID);
-//     }
-//   }];
-//
+/**
+ Returns an operation to expunge a folder.
+
+     MCOIMAPOperation * op = [session expungeOperation:@"INBOX"];
+     [op start:^(NSError * error) {
+          ...
+     }];
+*/
+- (MCOIMAPOperation *) expungeOperation:(NSString *)folder;
+
+/** @name Message Actions */
+
+/**
+ Returns an operation to add a message to a folder.
+
+     MCOIMAPOperation * op = [session appendMessageOperationWithFolder:@"Sent Mail" messageData:rfc822Data flags:MCOMessageFlagNone];
+     [op start:^(NSError * error, uint32_t createdUID) {
+       if (error == nil) {
+         NSLog(@"created message with UID %lu", (unsigned long) createdUID);
+       }
+     }];
+*/
 - (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 * op = [session copyMessagesOperationWithFolder:@"INBOX"
-//                                                                           uids:[MCIndexSet indexSetWithIndex:456]
-//                                                                     destFolder:@"Cocoa"];
-//   [op start:^(NSError * error, MCOIndexSet * destUids) {
-//        NSLog(@"copied to folder with UID %@", destUids);
-//   }];
-//
+/**
+ Returns an operation to copy messages to a folder.
+
+     MCOIMAPCopyMessagesOperation * op = [session copyMessagesOperationWithFolder:@"INBOX"
+                                                                             uids:[MCIndexSet indexSetWithIndex:456]
+                                                                       destFolder:@"Cocoa"];
+     [op start:^(NSError * error, MCOIndexSet * destUids) {
+          NSLog(@"copied to folder with UID %@", destUids);
+     }];
+*/
 - (MCOIMAPCopyMessagesOperation *)copyMessagesOperationWithFolder:(NSString *)folder
                                                              uids:(MCOIndexSet *)uids
                                                        destFolder:(NSString *)destFolder NS_RETURNS_NOT_RETAINED;
 
+/**
+ Returns an operation to change flags of messages.
 
-// Returns an operation to expunge a folder.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIMAPOperation * op = [session expungeOperation:@"INBOX"];
-//   [op start:^(NSError * error) {
-//        ...
-//   }];
-//
-- (MCOIMAPOperation *) expungeOperation:(NSString *)folder;
+ For example: Adds the seen flag to the message with UID 456.
 
-// Returns an operation to fetch messages by UID.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIMAPFetchMessagesOperation * op = [session fetchMessagesByUIDOperationWithFolder:@"INBOX"
-//                                                                           requestKind:MCOIMAPMessagesRequestKindHeaders | MCOIMAPMessagesRequestKindStructure
-//                                                                                  uids:MCORangeMake(1, UINT64_MAX)];
-//   [op start:^(NSError * error, NSArray * /* MCOIMAPMessage */ messages, MCOIndexSet * vanishedMessages) {
-//      for(MCOIMAPMessage * msg in messages) {
-//        NSLog(@"%lu: %@", [msg uid], [msg header]);
-//      }
-//   }];
-//
+     MCOIMAPOperation * op = [session storeFlagsOperationWithFolder:@"INBOX"
+                                                               uids:[MCOIndexSet indexSetWithIndex:456]
+                                                               kind:MCOIMAPStoreFlagsRequestKindAdd
+                                                              flags:MCOMessageFlagSeen];
+     [op start:^(NSError * error) {
+          ...
+     }];
+*/
+- (MCOIMAPOperation *) storeFlagsOperationWithFolder:(NSString *)folder
+                                                uids:(MCOIndexSet *)uids
+                                                kind:(MCOIMAPStoreFlagsRequestKind)kind
+                                               flags:(MCOMessageFlag)flags;
+/**
+ Returns an operation to change labels of messages. Intended for Gmail
+
+ For example: Adds the label "Home" flag to the message with UID 456.
+
+     MCOIMAPOperation * op = [session storeFlagsOperationWithFolder:@"INBOX"
+                                                               uids:[MCOIndexSet indexSetWithIndex:456]
+                                                               kind:MCOIMAPStoreFlagsRequestKindAdd
+                                                             labels:[NSArray arrayWithObject:@"Home"]];
+     [op start:^(NSError * error) {
+          ...
+     }];
+*/
+- (MCOIMAPOperation *) storeLabelsOperationWithFolder:(NSString *)folder
+                                                 uids:(MCOIndexSet *)uids
+                                                 kind:(MCOIMAPStoreFlagsRequestKind)kind
+                                               labels:(NSArray *)labels;
+
+/** @name Fetching Messages */
+
+/**
+ Returns an operation to fetch messages by UID.
+
+     MCOIMAPFetchMessagesOperation * op = [session fetchMessagesByUIDOperationWithFolder:@"INBOX"
+                                                                             requestKind:MCOIMAPMessagesRequestKindHeaders | MCOIMAPMessagesRequestKindStructure
+                                                                                    uids:MCORangeMake(1, UINT64_MAX)];
+     [op start:^(NSError * error, NSArray * messages, MCOIndexSet * vanishedMessages) {
+        for(MCOIMAPMessage * msg in messages) {
+          NSLog(@"%lu: %@", [msg uid], [msg header]);
+        }
+     }];
+*/
 - (MCOIMAPFetchMessagesOperation *) fetchMessagesByUIDOperationWithFolder:(NSString *)folder
                                                               requestKind:(MCOIMAPMessagesRequestKind)requestKind
                                                                      uids:(MCOIndexSet *)uids;
 
-// Returns an operation to fetch messages by number.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   // show 50 most recent uids.
-//   MCOIMAPFetchMessagesOperation * op = [session fetchMessagesByNumberOperationWithFolder:@"INBOX"
-//                                                                              requestKind:MCOIMAPMessagesRequestKindUID
-//                                                                                     uids:MCORangeMake(messageCount - 50, messageCount)];
-//   [op start:^(NSError * error, NSArray * /* MCOIMAPMessage */ messages, MCOIndexSet * vanishedMessages) {
-//      for(MCOIMAPMessage * msg in messages) {
-//        NSLog(@"%lu", [msg uid]);
-//      }
-//   }];
-//
+/**
+ Returns an operation to fetch messages by (sequence) number.
+ For example: show 50 most recent uids.
+     MCOIMAPFetchMessagesOperation * op = [session fetchMessagesByNumberOperationWithFolder:@"INBOX"
+                                                                                requestKind:MCOIMAPMessagesRequestKindUID
+                                                                                       uids:MCORangeMake(messageCount - 50, messageCount)];
+     [op start:^(NSError * error, NSArray * messages, MCOIndexSet * vanishedMessages) {
+        for(MCOIMAPMessage * msg in messages) {
+          NSLog(@"%lu", [msg uid]);
+        }
+     }];
+*/
 - (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 * op = [session syncMessagesByUIDWithFolder:@"INBOX"
-//                                                                 requestKind:MCOIMAPMessagesRequestKindUID
-//                                                                        uids:MCORangeMake(1, UINT64_MAX)
-//                                                                      modSeq:lastModSeq];
-//   [op start:^(NSError * error, NSArray * /* MCOIMAPMessage */ messages, MCOIndexSet * vanishedMessages) {
-//     NSLog(@"added or modified messages: %@", messages);
-//     NSLog(@"deleted messages: %@", vanishedMessages);
-//   }];
-//
+/**
+ Returns an operation to sync the last changes related to the given message list given a modSeq.
+
+     MCOIMAPFetchMessagesOperation * op = [session syncMessagesByUIDWithFolder:@"INBOX"
+                                                                   requestKind:MCOIMAPMessagesRequestKindUID
+                                                                          uids:MCORangeMake(1, UINT64_MAX)
+                                                                        modSeq:lastModSeq];
+     [op start:^(NSError * error, NSArray * messages, MCOIndexSet * vanishedMessages) {
+       NSLog(@"added or modified messages: %@", messages);
+       NSLog(@"deleted messages: %@", vanishedMessages);
+     }];
+
+@warn *Important*: This is only for servers that support Conditional Store. See [RFC4551](http://tools.ietf.org/html/rfc4551)
+*/
 - (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 * op = [session fetchMessageByUIDOperationWithFolder:@"INBOX" uid:456 urgent:NO];
-//   [op start:^(NSError * error, NSData * messageData) {
-//      MCOMessageParser * parser = [MCOMessageParser messageParserWithData:messageData]
-//      ...
-//   }];
-//
+/**
+ Returns an operation to fetch the content of a message.
+ @param urgent is set to YES, an additional connection to the same folder might be opened to fetch the content.
+
+     MCOIMAPFetchContentOperation * op = [session fetchMessageByUIDOperationWithFolder:@"INBOX" uid:456 urgent:NO];
+     [op start:^(NSError * error, NSData * messageData) {
+        MCOMessageParser * parser = [MCOMessageParser messageParserWithData:messageData]
+        ...
+     }];
+*/
 - (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 * op = [session fetchMessageByUIDOperationWithFolder:@"INBOX" uid:456];
-//   [op start:^(NSError * error, NSData * messageData) {
-//      MCOMessageParser * parser = [MCOMessageParser messageParserWithData:messageData]
-//      ...
-//   }];
-//
+/**
+ Returns an operation to fetch the content of a message.
+
+     MCOIMAPFetchContentOperation * op = [session fetchMessageByUIDOperationWithFolder:@"INBOX" uid:456];
+     [op start:^(NSError * error, NSData * messageData) {
+        MCOMessageParser * parser = [MCOMessageParser messageParserWithData:messageData]
+        ...
+     }];
+*/
 - (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 * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX"
-//                                                                                           uid:456
-//                                                                                        partID:@"1.2"
-//                                                                                      encoding:MCOEncodingBase64
-//                                                                                        urgent:YES];
-//   [op start:^(NSError * error, NSData * partData) {
-//      ...
-//   }];
-//
+/** @name Fetching Attachment Operations */
+
+/**
+ Returns an operation to fetch an attachment.
+ @param  urgent is set to YES, an additional connection to the same folder might be opened to fetch the content.
+
+     MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX"
+                                                                                             uid:456
+                                                                                          partID:@"1.2"
+                                                                                        encoding:MCOEncodingBase64
+                                                                                          urgent:YES];
+     [op start:^(NSError * error, NSData * partData) {
+        ...
+     }];
+*/
 - (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.
-//
-// Example 1:
-// {
-//   ...
-//   MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX"
-//                                                                                           uid:456
-//                                                                                        partID:@"1.2"
-//                                                                                      encoding:MCOEncodingBase64];
-//   [op start:^(NSError * error, NSData * partData) {
-//      ...
-//   }];
-//
-// Example 2:
-// {
-//   ...
-//   MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX"
-//                                                                                           uid:[message uid]
-//                                                                                        partID:[part partID]
-//                                                                                      encoding:[part encoding]];
-//   [op start:^(NSError * error, NSData * partData) {
-//      ...
-//   }];
-//
+/**
+  Returns an operation to fetch an attachment.
+
+  Example 1:
+
+     MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX"
+                                                                                             uid:456
+                                                                                          partID:@"1.2"
+                                                                                        encoding:MCOEncodingBase64];
+     [op start:^(NSError * error, NSData * partData) {
+        ...
+     }];
+  
+  Example 2:
+
+     MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX"
+                                                                                             uid:[message uid]
+                                                                                          partID:[part partID]
+                                                                                        encoding:[part encoding]];
+     [op start:^(NSError * error, NSData * partData) {
+        ...
+     }];
+*/
 - (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.
-//
-// Adds the seen flag to the message with UID 456.
-// {
-//   ...
-//   MCOIMAPOperation * op = [session storeFlagsOperationWithFolder:@"INBOX"
-//                                                             uids:[MCOIndexSet indexSetWithIndex:456]
-//                                                             kind:MCOIMAPStoreFlagsRequestKindAdd
-//                                                            flags:MCOMessageFlagSeen];
-//   [op start:^(NSError * error) {
-//        ...
-//   }];
-//
-- (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.
-//
-// Adds the label "Home" flag to the message with UID 456.
-// {
-//   ...
-//   MCOIMAPOperation * op = [session storeFlagsOperationWithFolder:@"INBOX"
-//                                                             uids:[MCOIndexSet indexSetWithIndex:456]
-//                                                             kind:MCOIMAPStoreFlagsRequestKindAdd
-//                                                           labels:[NSArray arrayWithObject:@"Home"]];
-//   [op start:^(NSError * error) {
-//        ...
-//   }];
-//
-- (MCOIMAPOperation *) storeLabelsOperationWithFolder:(NSString *)folder
-                                                 uids:(MCOIndexSet *)uids
-                                                 kind:(MCOIMAPStoreFlagsRequestKind)kind
-                                               labels:(NSArray *)labels;
+/** @name General IMAP Actions */
 
-// Returns an operation to search for messages with a simple match.
-// The operation needs to be started.
-//
-//   ...
-//   MCOIMAPSearchOperation * op = [session searchOperationWithFolder:@"INBOX"
-//                                                               kind:MCOIMAPSearchKindFrom
-//                                                       searchString:@"laura"];
-//   [op start:^(NSError * error, MCOIndexSet * searchResult) {
-//        ...
-//   }];
-//
-- (MCOIMAPSearchOperation *) searchOperationWithFolder:(NSString *)folder
-                                                  kind:(MCOIMAPSearchKind)kind
-                                          searchString:(NSString *)searchString;
+/**
+ Returns an operation to wait for something to happen in the folder.
+ See [RFC2177](http://tools.ietf.org/html/rfc2177) for me info.
 
-// Returns an operation to search for messages.
-// The operation needs to be started.
-//
-//   ...
-//   MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"]
-//   MCOIMAPSearchOperation * op = [session searchExpressionOperationWithFolder:@"INBOX"
-//                                                                   expression:expr];
-//   [op start:^(NSError * error, MCOIndexSet * searchResult) {
-//        ...
-//   }];
-//
-- (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 * op = [session idleOperationWithFolder:@"INBOX"
-//                                                   lastKnownUID:0];
-//   [op start:^(NSError * error) {
-//        ...
-//   }];
-//
+     MCOIMAPIdleOperation * op = [session idleOperationWithFolder:@"INBOX"
+                                                     lastKnownUID:0];
+     [op start:^(NSError * error) {
+          ...
+     }];
+*/
 - (MCOIMAPIdleOperation *) idleOperationWithFolder:(NSString *)folder
                                       lastKnownUID:(uint32_t)lastKnownUID;
 
-// Returns an operation to fetch the list of namespaces.
-// The operation needs to be started.
-//
-//   ...
-//   MCOIMAPFetchNamespaceOperation * op = [session fetchNamespaceOperation];
-//   [op start:^(NSError * error, NSDictionary * namespaces) {
-//     if (error != nil)
-//       return;
-//     MCOIMAPNamespace * ns = [namespace objectForKey:MCOIMAPNamespacePersonal];
-//     NSString * path = [ns pathForComponents:[NSArray arrayWithObject:]];
-//     MCOIMAPOperation * createOp = [session createFolderOperation:foobar];
-//     [createOp start:^(NSError * error) {
-//       ...
-//     }];
-//   }];
-//
+/** 
+ Returns an operation to fetch the list of namespaces.
+
+     MCOIMAPFetchNamespaceOperation * op = [session fetchNamespaceOperation];
+     [op start:^(NSError * error, NSDictionary * namespaces) {
+       if (error != nil)
+         return;
+       MCOIMAPNamespace * ns = [namespace objectForKey:MCOIMAPNamespacePersonal];
+       NSString * path = [ns pathForComponents:[NSArray arrayWithObject:]];
+       MCOIMAPOperation * createOp = [session createFolderOperation:foobar];
+       [createOp start:^(NSError * error) {
+         ...
+       }];
+     }];
+*/
 - (MCOIMAPFetchNamespaceOperation *) fetchNamespaceOperation;
 
-// Returns an operation to send/get identity.
-// The operation needs to be started.
-//
-//   ...
-//   MCOIMAPIdentityOperation * op = [session identityOperationWithVendor:@"Mozilla"
-//                                                                   name:@"Thunderbird"
-//                                                                version:@"17.0.5"];
-//   [op start:^(NSError * error, NSDictionary * serverIdentity) {
-//        ...
-//   }];
-//
+/**
+ Returns an operation to send the client or get the server identity.
+
+     MCOIMAPIdentityOperation * op = [session identityOperationWithVendor:@"Mozilla"
+                                                                     name:@"Thunderbird"
+                                                                  version:@"17.0.5"];
+     [op start:^(NSError * error, NSDictionary * serverIdentity) {
+          ...
+     }];
+*/
 - (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) {
-//        ...
-//   }]];
-//
+
+/**
+ Returns an operation that will check whether the IMAP account is valid.
+
+     MCOIMAPOperation * op = [session checkAccountOperation];
+     [op start:^(NSError * error) {
+          ...
+     }];
+*/
 - (MCOIMAPOperation *) checkAccountOperation;
 
-// Returns an operation to request capabilities of the server.
-// See MCOIMAPCapability for the list of capabilities.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   canIdle = NO;
-//   MCOIMAPCapabilityOperation * op = [session capabilityOperation];
-//   [op start:^(NSError * error, MCOIndexSet * capabilities) {
-//     if ([capabilities containsIndex:MCOIMAPCapabilityIdle]) {
-//       canIdle = YES;
-//     }
-//   }]];
-//
+/**
+ Returns an operation to request capabilities of the server.
+ See MCOIMAPCapability for the list of capabilities.
+
+     canIdle = NO;
+     MCOIMAPCapabilityOperation * op = [session capabilityOperation];
+     [op start:^(NSError * error, MCOIndexSet * capabilities) {
+       if ([capabilities containsIndex:MCOIMAPCapabilityIdle]) {
+         canIdle = YES;
+       }
+     }];
+*/
 - (MCOIMAPCapabilityOperation *) capabilityOperation;
 
+/** @name Search Operations */
+
+/**
+ Returns an operation to search for messages with a simple match.
+
+     MCOIMAPSearchOperation * op = [session searchOperationWithFolder:@"INBOX"
+                                                                 kind:MCOIMAPSearchKindFrom
+                                                         searchString:@"laura"];
+     [op start:^(NSError * error, MCOIndexSet * searchResult) {
+          ...
+     }];
+*/
+- (MCOIMAPSearchOperation *) searchOperationWithFolder:(NSString *)folder
+                                                  kind:(MCOIMAPSearchKind)kind
+                                          searchString:(NSString *)searchString;
+
+/**
+ Returns an operation to search for messages.
+
+     MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"]
+     MCOIMAPSearchOperation * op = [session searchExpressionOperationWithFolder:@"INBOX"
+                                                                     expression:expr];
+     [op start:^(NSError * error, MCOIndexSet * searchResult) {
+          ...
+     }];
+*/
+- (MCOIMAPSearchOperation *) searchExpressionOperationWithFolder:(NSString *)folder
+                                                      expression:(MCOIMAPSearchExpression *)expression;
+
 @end
 
 #endif
diff --git a/src/objc/pop/MCOPOPFetchHeaderOperation.h b/src/objc/pop/MCOPOPFetchHeaderOperation.h
index d395df5b..76826f56 100644
--- a/src/objc/pop/MCOPOPFetchHeaderOperation.h
+++ b/src/objc/pop/MCOPOPFetchHeaderOperation.h
@@ -13,17 +13,25 @@
 #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.
+/** 
+ This is an asynchronous operation that will fetch the header of a message.
+ @See MCOPOPSession
+*/
 
 @class MCOMessageHeader;
 
 @interface MCOPOPFetchHeaderOperation : MCOPOPOperation
 
-// 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.
+/** 
+ Starts the asynchronous fetch operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `header` will contain the message header
+ 
+ - On failure, `error` will be set with `MCOErrorDomain` as domain and an 
+   error code available in MCOConstants.h, `header` will be null
+*/
 - (void) start:(void (^)(NSError * error, MCOMessageHeader * header))completionBlock;
 
 @end
diff --git a/src/objc/pop/MCOPOPFetchMessageOperation.h b/src/objc/pop/MCOPOPFetchMessageOperation.h
index 86149e08..d8091b25 100644
--- a/src/objc/pop/MCOPOPFetchMessageOperation.h
+++ b/src/objc/pop/MCOPOPFetchMessageOperation.h
@@ -13,20 +13,25 @@
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOPOPOperation.h>
 
-// This is an asynchronous operation that will fetch the content of a message.
+/** Fetch a message from POP3 */
 
 typedef void (^MCOPOPOperationProgressBlock)(unsigned int current, unsigned int maximum);
 
 @interface MCOPOPFetchMessageOperation : MCOPOPOperation
 
-// This block will be called during the progression while downloading the message
-// when some bytes have been downloaded from the network.
+/** This block will be called as data is downloaded from the network */
 @property (nonatomic, copy) MCOPOPOperationProgressBlock progress;
 
-// 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.
+/** 
+ Starts the asynchronous fetch operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `data` will contain the message data
+ 
+ - 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 * messageData))completionBlock;
 
 @end
diff --git a/src/objc/pop/MCOPOPFetchMessagesOperation.h b/src/objc/pop/MCOPOPFetchMessagesOperation.h
index caad35b5..f63d2c5f 100644
--- a/src/objc/pop/MCOPOPFetchMessagesOperation.h
+++ b/src/objc/pop/MCOPOPFetchMessagesOperation.h
@@ -13,15 +13,20 @@
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOPOPOperation.h>
 
-// This is an asynchronous operation that will fetch the list of a messages on the account.
+/** This is an asynchronous operation that will fetch the list of a messages on the POP3 account. */
 
 @interface MCOPOPFetchMessagesOperation : MCOPOPOperation
 
-// 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.
+/** 
+ Starts the asynchronous fetch operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil and `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, `messages` will be null
+*/
 - (void) start:(void (^)(NSError * error, NSArray * /* MCOPOPMessageInfo */ messages))completionBlock;
 
 @end
diff --git a/src/objc/pop/MCOPOPMessageInfo.h b/src/objc/pop/MCOPOPMessageInfo.h
index bef874ff..b1780a96 100644
--- a/src/objc/pop/MCOPOPMessageInfo.h
+++ b/src/objc/pop/MCOPOPMessageInfo.h
@@ -12,18 +12,18 @@
 
 #import <Foundation/Foundation.h>
 
-// This is information of a message fetched by MCOPOPFetchMessagesOperation.
+/** This is information of a message fetched by MCOPOPFetchMessagesOperation.*/
 
 @interface MCOPOPMessageInfo : NSObject <NSCopying>
 
-// This is the index of a given message.
+/** This is the index of a given message.*/
 @property (nonatomic, assign) unsigned int index;
 
-// This is the size of the given message.
+/** 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.
+/** 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 656b57a1..d2b3105e 100644
--- a/src/objc/pop/MCOPOPOperation.h
+++ b/src/objc/pop/MCOPOPOperation.h
@@ -13,13 +13,23 @@
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOOperation.h>
 
-// This is an asynchronous POP3 operation.
-// See MCOPOPSession for more info.
+/**
+ This is a generic asynchronous POP3 operation. 
+ @see MCOPOPSession
+*/
 
 @interface MCOPOPOperation : MCOOperation
 
-// 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.
+/** 
+ Starts the asynchronous operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil
+ 
+ - 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/pop/MCOPOPSession.h b/src/objc/pop/MCOPOPSession.h
index aa1f2904..52f5a9b7 100644
--- a/src/objc/pop/MCOPOPSession.h
+++ b/src/objc/pop/MCOPOPSession.h
@@ -20,102 +20,95 @@
 @class MCOPOPOperation;
 @class MCOIndexSet;
 
-// This class implements asynchronous POP3 protocol.
+/** This class implements asynchronous access to the POP3 protocol.*/
 
 @interface MCOPOPSession : NSObject
 
-// This is the hostname of the POP3 server to connect to.
+/** 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.
+/** This is the port of the POP3 server to connect to.*/
 @property (nonatomic, assign) unsigned int port;
 
-// This is the username of the account.
+/** This is the username of the account.*/
 @property (nonatomic, copy) NSString * username;
 
-// This is the password of the account.
+/** 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.
+/** 
+ This is the authentication type to use to connect.
+ `MCOAuthTypeSASLNone` means that it uses the clear-text is used (and is the default).
+ @warning *Important*: Over an encrypted connection like TLS, the password will still be secure
+*/
 @property (nonatomic, assign) MCOAuthType authType;
 
-// This is the encryption type to use.
-// See MCOConnectionType for more information.
+/** This is the encryption type to use.
+See MCOConnectionType for more information.*/
 @property (nonatomic, assign) MCOConnectionType connectionType;
 
-// This is the timeout of the connection.
+/** 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.
+/** 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.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   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.
-//   }];
-//
+/** @name Operations */
+
+/**
+ 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.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOPOPFetchHeaderOperation * op = [session fetchHeaderOperationWithIndex:idx];
-//   [op start:^(NSError * error, MCOMessageHeader * header) {
-//        // header is the parsed header of the message.
-//   }];
-//
+/**
+ 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.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOPOPFetchMessageOperation * op = [session fetchMessageOperationWithIndex:idx];
-//   [op start:^(NSError * error, NSData * messageData) {
-//        // messageData is the RFC 822 formatted message data.
-//   }];
-//
+/**
+ 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;
 
-// Returns an operation that will delete the given messages.
-// Will disconnect when finished.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOIndexSet * indexes = [MCOIndexSet indexSet];
-//   [indexes addIndex:1];
-//   [indexes addIndex:2];
-//   [indexes addIndex:3];
-//   MCOPOPOperation * op = [session deleteMessagesOperationWithIndexes:indexes];
-//   [op start:^(NSError * error) {
-//        ...
-//   }];
-//
+/**
+ 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;
 
-// Returns an operation that will check whether the POP account is valid.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOPOPOperation * op = [session checkAccountOperation];
-//   [op start:^(NSError * error) {
-//        ...
-//   }];
-//
+/**
+ Returns an operation that will check whether the POP account is valid.
+
+     MCOPOPOperation * op = [session checkAccountOperation];
+     [op start:^(NSError * error) {
+          ...
+     }];
+*/
 - (MCOPOPOperation *) checkAccountOperation;
 
 @end
diff --git a/src/objc/rfc822/MCOAttachment.h b/src/objc/rfc822/MCOAttachment.h
index 584bdece..50a2d1a7 100644
--- a/src/objc/rfc822/MCOAttachment.h
+++ b/src/objc/rfc822/MCOAttachment.h
@@ -12,30 +12,31 @@
 
 #import <MailCore/MCOAbstractPart.h>
 
-// This is a single part.
-// It can either parsed from RFC 822 message data or created to build a message.
+/** This is a single part.
+
+    It can either parsed from RFC 822 message data or created to build a message.*/
 
 @interface MCOAttachment : MCOAbstractPart <NSCopying>
 
-// Returns a MIME type for a filename.
+/** Returns a MIME type for a filename.*/
 + (NSString *) mimeTypeForFilename:(NSString *)filename;
 
-// Returns a file attachment with the content of the given file.
+/** Returns a file attachment with the content of the given file.*/
 + (MCOAttachment *) attachmentWithContentsOfFile:(NSString *)filename;
 
-// Returns a part with an HTML content.
+/** Returns a part with an HTML content.*/
 + (MCOAttachment *) attachmentWithHTMLString:(NSString *)htmlString;
 
-// Returns a part with a RFC 822 messsage attachment.
+/** Returns a part with a RFC 822 messsage attachment.*/
 + (MCOAttachment *) attachmentWithRFC822Message:(NSData *)messageData;
 
-// Returns a part with an plain text content.
+/** Returns a part with an plain text content.*/
 + (MCOAttachment *) attachmentWithText:(NSString *)text;
 
-// Decoded data of the part.
+/** Decoded data of the part.*/
 @property (nonatomic, strong) NSData * data;
 
-// Returns string representation according to charset
+/** Returns string representation according to charset*/
 - (NSString *) decodedString;
  
 @end
diff --git a/src/objc/rfc822/MCOMessageBuilder.h b/src/objc/rfc822/MCOMessageBuilder.h
index a01e3350..4fa78691 100644
--- a/src/objc/rfc822/MCOMessageBuilder.h
+++ b/src/objc/rfc822/MCOMessageBuilder.h
@@ -12,60 +12,53 @@
 
 #import <MailCore/MCOAbstractMessage.h>
 
-// This class will allow you to build a RFC 822 formatted message.
-// For example when you need to send a message using SMTP,
-// you need to generate first a RFC 822 formatted message.
-// This class will help you do that.
-
-/*
+/**
+ This class will allow you to build a RFC 822 formatted message.
+ For example when you need to send a message using SMTP,
+ you need to generate first a RFC 822 formatted message.
+ This class will help you do that.
  
-{
-  ...
-  MCOMessageBuilder * builder = [[MCOMessageBuilder alloc] init];
-  [[builder header] setFrom:[MCOAddress addressWithDisplayName:@"Hoa V. DINH" mailbox:@"hoa@etpan.org"];
-  NSArray * to = [NSArray arrayWithObject:[MCOAddress addressWithDisplayName:@"Gael Roualland" mailbox:@"gael@etpan.org"]];
-  [[builder header] setTo:to];
-  [[builder header] setSubject:@"A nice picture!"];
-  [builder setHTMLBody:@"<div>Here's the message I need to send.</div>"];
-  [builder addAttachment:[MCOAttachment attachmentWithContentsOfFile:@"/Users/foo/Pictures/image.jpg"]];
-  NSData * rfc822Data = [builder data];
-  ...
-}
+    MCOMessageBuilder * builder = [[MCOMessageBuilder alloc] init];
+    [[builder header] setFrom:[MCOAddress addressWithDisplayName:@"Hoa V. DINH" mailbox:@"hoa@etpan.org"];
+    NSArray * to = [NSArray arrayWithObject:[MCOAddress addressWithDisplayName:@"Gael Roualland" mailbox:@"gael@etpan.org"]];
+    [[builder header] setTo:to];
+    [[builder header] setSubject:@"A nice picture!"];
+    [builder setHTMLBody:@"<div>Here's the message I need to send.</div>"];
+    [builder addAttachment:[MCOAttachment attachmentWithContentsOfFile:@"/Users/foo/Pictures/image.jpg"]];
+    NSData * rfc822Data = [builder data];
  
- */
+*/
 
 @class MCOAttachment;
 @protocol MCOHTMLRendererDelegate;
 
 @interface MCOMessageBuilder : MCOAbstractMessage <NSCopying>
 
-// Main HTML content of the message.
+/** Main HTML content of the message.*/
 @property (nonatomic, copy, setter=setHTMLBody:) NSString * htmlBody;
 
-// Plain text content of the message.
+/** Plain text content of the message.*/
 @property (nonatomic, copy) NSString * textBody;
 
-// List of file attachments.
+/** List of file attachments.*/
 @property (nonatomic, copy) NSArray * attachments;
 
-// List of related file attachments (included as cid: link in the HTML part).
+/** List of related file attachments (included as cid: link in the HTML part).*/
 @property (nonatomic, copy) NSArray * relatedAttachments;
 
-// Prefix for the boundary identifier.
-// Default value is nil.
+/** Prefix for the boundary identifier. Default value is nil.*/
 @property (nonatomic, copy) NSString * boundaryPrefix;
 
-// Add an attachment.
+/** Add an attachment.*/
 - (void) addAttachment:(MCOAttachment *)attachment;
 
-// Add a related attachment.
+/** Add a related attachment.*/
 - (void) addRelatedAttachment:(MCOAttachment *)attachment;
 
-// RFC 822 formatted message.
+/** RFC 822 formatted message.*/
 - (NSData *) data;
 
-// HTML rendering of the message to be displayed in a web view.
-// The delegate can be nil.
+/** HTML rendering of the message to be displayed in a web view. The delegate can be nil.*/
 - (NSString *) htmlRenderingWithDelegate:(id <MCOHTMLRendererDelegate>)delegate;
 
 @end
diff --git a/src/objc/rfc822/MCOMessageParser.h b/src/objc/rfc822/MCOMessageParser.h
index c0df2fbb..fa46132b 100644
--- a/src/objc/rfc822/MCOMessageParser.h
+++ b/src/objc/rfc822/MCOMessageParser.h
@@ -10,9 +10,11 @@
 
 #define __MAILCORE_MCOMESSAGEPARSER_H_
 
-// This class implements a parsed message.
-// When the full content of a message has been fetched using POP or IMAP,
-// you need to parse it.
+/**
+ This class implements a parsed message.
+ When the full content of a message has been fetched using POP or IMAP,
+ you need to parse it.
+*/
 
 #import <MailCore/MCOAbstractMessage.h>
 
@@ -20,21 +22,20 @@
 
 @interface MCOMessageParser : MCOAbstractMessage <NSCopying>
 
-// returns a parsed message from the given RFC 822 data.
+/** returns a parsed message from the given RFC 822 data.*/
 + (MCOMessageParser *) messageParserWithData:(NSData *)data;
 
-// data is the RFC 822 formatted message.
+/** data is the RFC 822 formatted message.*/
 - (id) initWithData:(NSData *)data;
 - (void) dealloc;
 
-// It's the main part of the message. It can be MCOMessagePart, MCOMultipart or MCOAttachment.
+/** It's the main part of the message. It can be MCOMessagePart, MCOMultipart or MCOAttachment.*/
 - (MCOAbstractPart *) mainPart;
 
-// data of the RFC 822 formatted message. It's the input of the parser.
+/** data of the RFC 822 formatted message. It's the input of the parser.*/
 - (NSData *) data;
 
-// HTML rendering of the message to be displayed in a web view.
-// delegate can be nil.
+/** HTML rendering of the message to be displayed in a web view. delegate can be nil.*/
 - (NSString *) htmlRenderingWithDelegate:(id <MCOHTMLRendererDelegate>)delegate;
 
 @end
diff --git a/src/objc/rfc822/MCOMessagePart.h b/src/objc/rfc822/MCOMessagePart.h
index 7d9d7f2c..a7055efc 100644
--- a/src/objc/rfc822/MCOMessagePart.h
+++ b/src/objc/rfc822/MCOMessagePart.h
@@ -12,7 +12,7 @@
 
 #import <MailCore/MCOAbstractMessagePart.h>
 
-// Message part parsed from RFC 822 message data.
+/** Message part parsed from RFC 822 message data. */
 
 @interface MCOMessagePart : MCOAbstractMessagePart <NSCopying>
 
diff --git a/src/objc/rfc822/MCOMultipart.h b/src/objc/rfc822/MCOMultipart.h
index 36922fe4..e45d4a0c 100644
--- a/src/objc/rfc822/MCOMultipart.h
+++ b/src/objc/rfc822/MCOMultipart.h
@@ -12,7 +12,7 @@
 
 #import <MailCore/MCOAbstractMultipart.h>
 
-// Multipart parsed from RFC 822 message data.
+/** Multipart parsed from RFC 822 message data. */
 
 @interface MCOMultipart : MCOAbstractMultipart <NSCopying>
 
diff --git a/src/objc/smtp/MCOSMTPOperation.h b/src/objc/smtp/MCOSMTPOperation.h
index 32d98dc8..7e6fa3f8 100644
--- a/src/objc/smtp/MCOSMTPOperation.h
+++ b/src/objc/smtp/MCOSMTPOperation.h
@@ -12,13 +12,20 @@
 
 #import <MailCore/MCOOperation.h>
 
-// This is an asynchronous SMTP operation.
+/** This is an asynchronous SMTP operation, used for sending messages. */
 
 @interface MCOSMTPOperation : MCOOperation
 
-// 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.
+/** 
+ Starts the asynchronous operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil
+ 
+ - 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/MCOSMTPSendOperation.h b/src/objc/smtp/MCOSMTPSendOperation.h
index e8a0f6b5..8e2dc56d 100644
--- a/src/objc/smtp/MCOSMTPSendOperation.h
+++ b/src/objc/smtp/MCOSMTPSendOperation.h
@@ -12,19 +12,25 @@
 
 #import <MailCore/MCOSMTPOperation.h>
 
-// This is an asynchronous operation that will send a message through SMTP.
+/** This is an asynchronous operation that will send a message through SMTP. */
 
 typedef void (^MCOSMTPOperationProgressBlock)(unsigned int current, unsigned int maximum);
 
 @interface MCOSMTPSendOperation : MCOSMTPOperation
 
-// This block will be called during the progression while sending the message
-// when some bytes have been sent to the network.
+/** This block will be called as the message is sent */
 @property (nonatomic, copy) MCOSMTPOperationProgressBlock progress;
 
-// 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.
+/* 
+ Starts the asynchronous operation.
+
+ @param completionBlock Called when the operation is finished.
+
+ - On success `error` will be nil
+ 
+ - 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 e0645eb1..08189bed 100644
--- a/src/objc/smtp/MCOSMTPSession.h
+++ b/src/objc/smtp/MCOSMTPSession.h
@@ -14,7 +14,12 @@
 
 #import <MailCore/MCOConstants.h>
 
-// This class implements asynchronous SMTP protocol.
+/** 
+ This class is used to create an SMTP connection and send messages
+
+ After calling a method that returns an operation you must call start: on the instance
+ to begin the operation.
+*/
 
 @class MCOSMTPSendOperation;
 @class MCOSMTPOperation;
@@ -22,63 +27,67 @@
 
 @interface MCOSMTPSession : NSObject
 
-// This is the hostname of the POP3 server to connect to.
+/** This is the hostname of the SMTP server to connect to. */
 @property (nonatomic, copy) NSString * hostname;
 
-// This is the port of the POP3 server to connect to.
+/** This is the port of the POP3 server to connect to. */
 @property (nonatomic, assign) unsigned int port;
 
-// This is the username of the account.
+/** This is the username of the account. */
 @property (nonatomic, copy) NSString * username;
 
-// This is the password of the account.
+/** 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.
+/** 
+ This is the authentication type to use to connect.
+ `MCOAuthTypeSASLNone` means that it uses the clear-text is used (and is the default).
+ @warning *Important*: Over an encrypted connection like TLS, the password will still be secure
+*/
 @property (nonatomic, assign) MCOAuthType authType;
 
-// This is the encryption type to use.
-// See MCOConnectionType for more information.
+/**
+ This is the encryption type to use.
+ See MCOConnectionType for more information.
+*/
 @property (nonatomic, assign) MCOConnectionType connectionType;
 
-// This is the timeout of the connection.
+/** 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.
+/** When set to YES, the connection will fail if the certificate is incorrect. */
 @property (nonatomic, assign, getter=isCheckCertificateEnabled) BOOL checkCertificateEnabled;
 
-// If set to YES, when sending the EHLO or HELO command, use IP address instead of hostname.
-// Default is NO.
+/**
+ If set to YES, when sending the EHLO or HELO command, use IP address instead of hostname.
+ Default is NO.
+*/
 @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.
-//
-// {
-//   ...
-//   // Generate RFC 822 data using MCOMessageBuilder
-//   MCOPOPOperation * op = [session sendOperationWithData:rfc822Data];
-//   [op start:^(NSError * error) {
-//        ...
-//   }];
-//
+/** @name Operations */
+
+/**
+ Returns an operation that will send the given message through SMTP.
+ 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.
+
+ Generate RFC 822 data using MCOMessageBuilder
+
+     MCOPOPOperation * op = [session sendOperationWithData:rfc822Data];
+     [op start:^(NSError * error) {
+          ...
+     }];
+*/
 - (MCOSMTPSendOperation *) sendOperationWithData:(NSData *)messageData;
 
-// Returns an operation that will check whether the SMTP account is valid.
-// The operation needs to be started.
-//
-// {
-//   ...
-//   MCOPOPOperation * op = [session checkAccountOperationWithFrom:[MCOAddress addressWithMailbox:@"hoa@etpan.org"]];
-//   [op start:^(NSError * error) {
-//        ...
-//   }];
-//
+/**
+ Returns an operation that will check whether the SMTP account is valid.
+
+     MCOPOPOperation * op = [session checkAccountOperationWithFrom:[MCOAddress addressWithMailbox:@"hoa@etpan.org"]];
+     [op start:^(NSError * error) {
+          ...
+     }];
+*/
 - (MCOSMTPOperation *) checkAccountOperationWithFrom:(MCOAddress *)from;
 
 @end
diff --git a/src/objc/utils/MCOIndexSet.h b/src/objc/utils/MCOIndexSet.h
index 1ecf8c9a..d80aa322 100644
--- a/src/objc/utils/MCOIndexSet.h
+++ b/src/objc/utils/MCOIndexSet.h
@@ -14,47 +14,47 @@
 
 #import <MailCore/MCORange.h>
 
-// similar to NSMutableIndexSet but supports int64_t
+/** similar to NSMutableIndexSet but supports int64_t*/
 
 @interface MCOIndexSet : NSObject <NSCopying>
 
-// Creates an empty index set.
+/** Creates an empty index set.*/
 + (MCOIndexSet *) indexSet;
 
-// Creates an index set that contains a range of integers.
+/** Creates an index set that contains a range of integers.*/
 + (MCOIndexSet *) indexSetWithRange:(MCORange)range;
 
-// Creates an index set with a single integer.
+/** Creates an index set with a single integer.*/
 + (MCOIndexSet *) indexSetWithIndex:(uint64_t)idx;
 
-// Returns the number of integers in that index set.
+/** Returns the number of integers in that index set.*/
 - (unsigned int) count;
 
-// Adds an integer to the index set.
+/** Adds an integer to the index set.*/
 - (void) addIndex:(uint64_t)idx;
 
-// Removes an integer from the index set.
+/** Removes an integer from the index set.*/
 - (void) removeIndex:(uint64_t)idx;
 
-// Returns YES if the index set contains the given integer.
+/** Returns YES if the index set contains the given integer.*/
 - (BOOL) containsIndex:(uint64_t)idx;
 
-// Adds a range of integers to the index set.
+/** Adds a range of integers to the index set.*/
 - (void) addRange:(MCORange)range;
 
-// Removes a range of integers from the index set.
+/** Removes a range of integers from the index set.*/
 - (void) removeRange:(MCORange)range;
 
-// Removes all integers that are not in the given range.
+/** Removes all integers that are not in the given range.*/
 - (void) intersectsRange:(MCORange)range;
 
-// Returns all the ranges of ths index set.
+/** Returns all the ranges of ths index set.*/
 - (MCORange *) allRanges;
 
-// Returns the number of ranges in this index set.
+/** Returns the number of ranges in this index set.*/
 - (unsigned int) rangesCount;
 
-// Enumerates all the indexes of the index set.
+/** Enumerates all the indexes of the index set.*/
 - (void) enumerateIndexes:(void (^)(uint64_t idx))block;
 
 @end
diff --git a/src/objc/utils/MCORange.h b/src/objc/utils/MCORange.h
index 4fdb9233..e3fac7fd 100644
--- a/src/objc/utils/MCORange.h
+++ b/src/objc/utils/MCORange.h
@@ -23,45 +23,45 @@ extern "C" {
 @class MCOIndexSet;
 
 typedef struct {
-    // first integer of the range.
+    /** first integer of the range.*/
     uint64_t location;
     
-    // length of the range.
+    /** length of the range.*/
     uint64_t length;
 } MCORange;
 
-// Constants for an emtpy range.
+/** Constants for an emtpy range.*/
 extern MCORange MCORangeEmpty;
 
-// Returns a new range given a location and length.
+/** Returns a new range given a location and length.*/
 MCORange MCORangeMake(uint64_t location, uint64_t length);
 
-// Returns an index set that is the result of sustracting a range from a range.
+/** Returns an index set that is the result of sustracting a range from a range.*/
 MCOIndexSet * MCORangeRemoveRange(MCORange range1, MCORange range2);
 
-// Returns an index set that is the result of the union a range from a range.
+/** Returns an index set that is the result of the union a range from a range.*/
 MCOIndexSet * MCORangeUnion(MCORange range1, MCORange range2);
 
 #ifdef __cplusplus
 
-// Returns a C++ range from an Objective-C range.
+/** Returns a C++ range from an Objective-C range.*/
 mailcore::Range MCORangeToMCRange(MCORange range);
 
-// Returns an Objective-C range from a C++ range.
+/** Returns an Objective-C range from a C++ range.*/
 MCORange MCORangeWithMCRange(mailcore::Range range);
 
 #endif
 
-// Returns the intersection of two ranges.
+/** Returns the intersection of two ranges.*/
 MCORange MCORangeIntersection(MCORange range1, MCORange range2);
 
-// Returns YES if two given ranges have an intersection.
+/** Returns YES if two given ranges have an intersection.*/
 BOOL MCORangeHasIntersection(MCORange range1, MCORange range2);
 
-// Returns left bound of a range.
+/** Returns left bound of a range.*/
 uint64_t MCORangeLeftBound(MCORange range);
 
-// Returns right bound of a range.
+/** Returns right bound of a range.*/
 uint64_t MCORangeRightBound(MCORange range);
 
 #ifdef __cplusplus