Documented the Obj-C API for providers

3 files changed, 94 insertions, 0 deletions

diff --git a/src/objc/provider/MCOMailProvider.h b/src/objc/provider/MCOMailProvider.h
index 6a5ed9b4..53f09736 100644
--- a/src/objc/provider/MCOMailProvider.h
+++ b/src/objc/provider/MCOMailProvider.h
@@ -8,25 +8,79 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+   Represents a email service provider, like for example Gmail, Yahoo, Fastmail.fm etc.
+*/
+
 @interface MCOMailProvider : NSObject
 
 @property (nonatomic, copy) NSString * identifier;
 
 - (id) initWithInfo:(NSDictionary *)info;
 
+/**
+   A list of ways that you can connect to the IMAP server
+   @return An array of MCONetService
+*/
 - (NSArray *) imapServices;
+
+/**
+   A list of ways that you can connect to the SMTP server
+   @return An array of MCONetService
+*/
 - (NSArray *) smtpServices;
+
+/**
+   A list of ways that you can connect to the POP3 server
+   @return An array of MCONetService
+*/
 - (NSArray *) popServices;
 
 - (BOOL) matchEmail:(NSString *)email;
 - (BOOL) matchMX:(NSString *)hostname;
 
+/**
+   Where sent mail is stored on the IMAP server
+   @return Returns nil if it is unknown
+*/
 - (NSString *) sentMailFolderPath;
+
+/**
+   Where starred mail is stored on the IMAP server.
+   This only applies to some servers like Gmail
+   @return Returns nil if it is unknown
+*/
 - (NSString *) starredFolderPath;
+
+/**
+   Where all mail or the archive folder is stored on the IMAP server
+   @return Returns nil if it is unknown
+*/
 - (NSString *) allMailFolderPath;
+
+/**
+   Where trash is stored on the IMAP server
+   @return Returns nil if it is unknown
+*/
 - (NSString *) trashFolderPath;
+
+/**
+   Where draft messages are stored on the IMAP server
+   @return Returns nil if it is unknown
+*/
 - (NSString *) draftsFolderPath;
+
+/**
+   Where spam messages are stored on the IMAP server
+   @return Returns nil if it is unknown
+*/
 - (NSString *) spamFolderPath;
+
+/**
+   Where important messages are stored on the IMAP server
+   This only applies to some servers, like Gmail
+   @return Returns nil if it is unknown
+*/
 - (NSString *) importantFolderPath;
 
 @end
diff --git a/src/objc/provider/MCOMailProvidersManager.h b/src/objc/provider/MCOMailProvidersManager.h
index 78d10ff2..1c4ef60f 100644
--- a/src/objc/provider/MCOMailProvidersManager.h
+++ b/src/objc/provider/MCOMailProvidersManager.h
@@ -8,14 +8,38 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+   This class is used to detect an email provider and it's associated
+   metadata either by MX record or by the email addresss.
+
+   An app might want to use this during setup to limit the number of settings
+   a user has to input.
+*/
+
 @class MCOMailProvider;
 
 @interface MCOMailProvidersManager : NSObject
 
+/** The shared manager that is used for all lookups */
 + (MCOMailProvidersManager *) sharedManager;
 
+/** 
+    Given an email address will try to determine the provider
+    @return The email provider info or nil if it can't be determined.
+*/
 - (MCOMailProvider *) providerForEmail:(NSString *)email;
+
+/** 
+    Given the DNS MX record will try to determine the provider
+    @return The email provider info or nil if it can't be determined.
+*/
 - (MCOMailProvider *) providerForMX:(NSString *)hostname;
+
+/**
+   Will return information about a provider. Useful if you already know the
+   provider (like if it has been determined previously)
+   @return The email provider info or nil if none matches
+*/
 - (MCOMailProvider *) providerForIdentifier:(NSString *)identifier;
 
 @end
diff --git a/src/objc/provider/MCONetService.h b/src/objc/provider/MCONetService.h
index 9eeb3649..482ae4dc 100644
--- a/src/objc/provider/MCONetService.h
+++ b/src/objc/provider/MCONetService.h
@@ -9,10 +9,22 @@
 #import <Foundation/Foundation.h>
 #import <MailCore/MCOConstants.h>
 
+/**
+   This class provides a specific way to access a given service
+*/
+
 @interface MCONetService : NSObject
 
+/**
+   The hostname of the server. [MCONetService hostnameWithEmail:] is recommended
+   instead as it can handle services with custom domains 
+*/
 @property (nonatomic, copy) NSString * hostname;
+
+/** The port number of the service */
 @property (nonatomic, assign) unsigned int port;
+
+/** What kind of connection type is supported, like SSL, Start TLS, Plain etc. */
 @property (nonatomic, assign) MCOConnectionType connectionType;
 
 + (MCONetService *) serviceWithInfo:(NSDictionary *)info;
@@ -20,6 +32,10 @@
 - (id) initWithInfo:(NSDictionary *)info;
 - (NSDictionary *) info;
 
+/** 
+    If the service uses a custom domain this will return the proper hostname based
+    off the email address
+*/
 - (NSString *) hostnameWithEmail:(NSString *)email;
 
 @end