add documentation

Classes/NWHub.h

@@ -18,15 +18,20 @@
 - (void)notification:(NWNotification *)notification didFailWithResult:(NWError)result; // TODO: deprecated, remove from 0.6.0
 @end
 
-/** Helper on top of NWPusher that hides the details of pushing and reading. */
+/** Helper on top of NWPusher that hides the details of pushing and reading.
+ 
+ This class provides a more convenient way of pushing notifications to the APNS server. It deals with the trouble of assigning a unique identifier to every notification and the handling of error responses from the server. It hides the latency that comes with transmitting the pushes, allowing you to simply push your notifications and getting notified of errors through the delegate. If this feels over-abstracted, then definitely check out the `NWPusher` class, which will give you full control.
+ 
+ There are two set of methods for pushing notifications: the easy and the pros. The former will just do the pushing and reconnect if the connection breaks. This is your low-worry solution, provided that you call `readFailed` every so often (seconds) to handle error data from the server. The latter will give you a little more control and a little more responsibility.
+ */
 @interface NWHub : NSObject
 
 /** @name Properties */
 
 /** The pusher instance that does the actual work. */
 @property (nonatomic, strong) NWPusher *pusher;
 
-/** Assign this delegate to get notified when something fails during or after pushing. */
+/** Assign a delegate to get notified when something fails during or after pushing. */
 @property (nonatomic, weak) id<NWHubDelegate> delegate;
 
 /** The type of notification serialization we'll be using. */
@@ -68,30 +73,73 @@
 
 /** @name Pushing (easy) */
 
-/** Push a JSON string payload to a device with token string. */
+/** Push a JSON string payload to a device with token string.
+ @see pushNotifications:
+ */
 - (NSUInteger)pushPayload:(NSString *)payload token:(NSString *)token;
 
-/** Push a JSON string payload to multiple devices with token strings. */
+/** Push a JSON string payload to multiple devices with token strings.
+ @see pushNotifications:
+ */
 - (NSUInteger)pushPayload:(NSString *)payload tokens:(NSArray *)tokens;
 
-/** Push multiple JSON string payloads to a device with token string. */
+/** Push multiple JSON string payloads to a device with token string.
+ @see pushNotifications:
+ */
 - (NSUInteger)pushPayloads:(NSArray *)payloads token:(NSString *)token;
 
-/** Push multiple notifications, each representing a payload and a device token. */
+/** Push multiple notifications, each representing a payload and a device token.
+ 
+ This will assign each notification a unique identifier if none was set yet. If pushing fails it will reconnect. This method can be used rather carelessly; any thing goes. However, this also means that a failed notification might break the connection temporarily, losing a notification here or there. If you are sending bulk and don't care too much about this, then you'll be fine. If not, consider using `pushNotification:autoReconnect:error:`.
+ 
+ Make sure to call `readFailed` on a regular basis to allow server error responses to be handled and the delegate to be called.
+ 
+ Returns the number of notifications that failed, preferably zero.
+ 
+ @see readFailed
+ */
 - (NSUInteger)pushNotifications:(NSArray *)notifications;
 
-/** Read the response from the server to see if any pushes have failed. */
+/** Read the response from the server to see if any pushes have failed.
+ 
+ Due to transmission latency it usually takes a couple of milliseconds for the server to respond to errors. This methods reads the server response and handles the errors. Make sure to call this regularly to catch up on malformed notifications.
+ 
+ @see pushNotifications:
+ */
 - (NSUInteger)readFailed;
 
 /** @name Pushing (pros) */
 
-/** Push a notification and reconnect if anything failed. */
+/** Push a notification and reconnect if anything failed. 
+ 
+ This will assign the notification a unique (incremental) identifier and feed it to the internal pusher. If this succeeds, the notification is stored for later lookup by `readFailed:autoReconnect:error:`. If it fails, the delegate will be invoked and it will reconnect if set to auto-reconnect.
+ 
+ @see readFailed:autoReconnect:error:
+ */
 - (BOOL)pushNotification:(NWNotification *)notification autoReconnect:(BOOL)reconnect error:(NSError **)error;
 
-/** Read the response from the server and reconnect if anything failed. */
+/** Read the response from the server and reconnect if anything failed.
+ 
+ If the APNS server finds something wrong with a notification, it will write back the identifier and error code. As this involves transmission to and from the server, it takes just a little while to get this failure info. This method should therefore be invoked a little (say a second) after pushing to see if anything was wrong. On a slow connection this might take longer than the interval between push messages, in which case the reported notification was *not* the last one sent.
+ 
+ From the server we only get the notification identifier and the error message. This method translates this back into the original notification by keeping track of all notifications sent in the past 30 seconds. If somehow the original notification cannot be found, it will assign `NSNull`.
+ 
+ Usually, when a notification fails, the server will drop the connection. To prevent this from causing any more problems, the connection can be reestablished by setting it to reconnect automatically.
+ 
+ @see trimIdentifiers
+ @see feedbackSpan
+ */
 - (BOOL)readFailed:(NWNotification **)notification autoReconnect:(BOOL)reconnect error:(NSError **)error;
 
-/** Let go of old notification, after you read the failed notifications. */
+/** Let go of old notification, after you read the failed notifications.
+ 
+ This class keeps track of all notifications sent so we can look them up later based on their identifier. This allows it to translate identifiers back into the original notification. To limit the amount of memory all older notifications should be trimmed from this lookup, which is done by this method. This is done based on the `feedbackSpan`, which defaults to 30 seconds.
+ 
+ Be careful not to call this function without first reading all failed notifications, using `readFailed:autoReconnect:error:`.
+ 
+ @see readFailed:autoReconnect:error:
+ @see feedbackSpan
+ */
 - (BOOL)trimIdentifiers;
 
 // deprecated

Classes/NWPusher.h

@@ -15,7 +15,7 @@
 
 /** @name Properties */
 
-/** The SSL connection though which all notifications are pushed. */
+/** The SSL connection through which all notifications are pushed. */
 @property (nonatomic, strong) NWSSLConnection *connection;
 
 /** @name Initialization */

Classes/NWSecTools.h

@@ -39,7 +39,7 @@
 + (NWCertificateRef)certificateWithData:(NSData *)data;
 
 #if !TARGET_OS_IPHONE
-/** Searches the OS Keychain for an identity (the key) that matches the certifiate. (OS X only) */
+/** Searches the OS Keychain for an identity (the key) that matches the certificate. (OS X only) */
 + (NWIdentityRef)keychainIdentityWithCertificate:(NWCertificateRef)certificate error:(NSError **)error;
 #endif
 

Classes/NWType.h

@@ -49,11 +49,11 @@ typedef NS_ENUM(NSInteger, NWError) {
     kNWErrorAPNInvalidPayloadSize              =   -7,
     /** APN invalid token. */
     kNWErrorAPNInvalidTokenContent             =   -8,
-    /** APN unkown reason. */
+    /** APN unknown reason. */
     kNWErrorAPNUnknownReason                   =   -9,
     /** APN shutdown. */
     kNWErrorAPNShutdown                        =  -10,
-    /** APN unkown error code. */
+    /** APN unknown error code. */
     kNWErrorAPNUnknownErrorCode                =  -11,
 
     /** Push response command unknown. */
@@ -74,7 +74,7 @@ typedef NS_ENUM(NSInteger, NWError) {
     kNWErrorSocketConnect                      = -201,
     /** Socket host cannot be resolved. */
     kNWErrorSocketResolveHostName              = -219,
-    /** Socket file contol failed. */
+    /** Socket file control failed. */
     kNWErrorSocketFileControl                  = -220,
     /** Socket options cannot be set. */
     kNWErrorSocketOptions                      = -221,
@@ -144,7 +144,7 @@ typedef NS_ENUM(NSInteger, NWError) {
     kNWErrorKeychainCreateIdentity             = -303,
 };
 
-/** A collection of helper methods to support Cocoa-sytle error handling (NSError). */
+/** A collection of helper methods to support Cocoa-style error handling (NSError). */
 @interface NWErrorUtil : NSObject
 
 /** @name Helpers */