Finished formatting docs for Appledoc for IMAP and SMTP

3 files changed, 70 insertions, 48 deletions

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