Finished formatting docs for Appledoc for IMAP and SMTP

27 files changed, 760 insertions, 612 deletions

diff --git a/scripts/gen-docs.sh b/scripts/gen-docs.sh
new file mode 100644
index 00000000..4760c83a
--- /dev/null
+++ b/scripts/gen-docs.sh
@@ -0,0 +1,12 @@
+appledoc \
+--no-create-docset \
+--no-install-docset \
+--project-name MailCore2 \
+--project-company "MailCore2" \
+--company-id com.mailcore2 \
+--logformat xcode \
+--ignore "*.m" \
+--no-warn-invalid-crossref \
+--no-repeat-first-par \
+--output ~/mailcore2-docs \
+src
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 cbeb64f2..39713e80 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;
 
 @end
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..18bfc192 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.
+/** 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/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