more documentation

CHANGLOG.md

@@ -3,8 +3,8 @@ Change Log
 
 ### master (unreleased)
 
-* Deprecated fetching
-* Documentation to all framework stuff
+* Deprecate fetching
+* Document all framework stuff
 
 ### 0.5.3 (2014-10-22)
 

Classes/NWHub.h

@@ -10,15 +10,18 @@
 
 @class NWNotification, NWPusher;
 
-/** Allows callback on errors while pushing to and reading from server. */
+/** Allows callback on errors while pushing to and reading from server. 
+ 
+ Check out `NWHub` for more details.
+ */
 @protocol NWHubDelegate <NSObject>
 /** The notification failed during or after pushing. */
 - (void)notification:(NWNotification *)notification didFailWithError:(NSError *)error;
 @optional
 - (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.
  

Classes/NWNotification.h

@@ -8,7 +8,16 @@
 #import "NWType.h"
 #import <Foundation/Foundation.h>
 
-/** A single push message, containing the receiver device token, the payload, and delivery attributes. */
+/** A single push message, containing the receiver device token, the payload, and delivery attributes.
+ 
+ This class represents a single push message, or *remote notification* as Apple calls it. It consists of device token, payload, and some optional attributes. The device token is a unique reference to a single installed app on a single Apple device. The payload is a JSON-formatted string that is delivered into the app. Among app-specific data, this payload contains information on how the device should handle and display this notification.
+ 
+ Then there is a number of additional attributes Apple has been adding over the years. The *identifier* is used in error data that we get back from the server. This allows us to associate the error with the notification. The *expiration* date tells the delivery system when it should stop trying to deliver the notification to the device. Priority indicates whether to conserve power on delivery.
+ 
+ There are different data formats into which a notification can be serialized. Older formats do not support all attributes. While this class supports all formats, it uses the latest format by default.
+ 
+ Read more about this in Apple's documentation under *Provider Communication with Apple Push Notification Service* and *The Notification Payload*.
+ */
 @interface NWNotification : NSObject
 
 /** @name Properties */

Classes/NWPushFeedback.h

@@ -10,7 +10,14 @@
 
 @class NWSSLConnection;
 
-/** Reads tokens and dates from the APNS Feedback Service. */
+/** Reads tokens and dates from the APNS Feedback Service.
+ 
+ The Feedback Service is a separate server that provides a list of all device tokens that it tried to deliver a notification to, but was unable to. This usually indicates that this device no longer has the app installed. This way, the Feedback Service provides reliable way of finding out who uninstalled the app, which can be fed back into your database.
+ 
+ Apple recommends reading from the service once a day. After a device token has been read, it will not be returned again until the next failed delivery. In practice: connect once a day, read all device tokens, and update your own database accordingly.
+ 
+ Read more in Apple's documentation under *The Feedback Service*.
+ */
 @interface NWPushFeedback : NSObject
 
 /** @name Properties */

Classes/NWPusher.h

@@ -10,7 +10,18 @@
 
 @class NWNotification, NWSSLConnection;
 
-/** Serializes notification objects and pushes them to the APNS. */
+/** Serializes notification objects and pushes them to the APNS. 
+ 
+ This is the heart of the framework. As the (inconvenient) name suggest, it's also one of the first classes that was added to the framework. This class provides a straightforward interface to the APNS server, including connecting, pushing to and reading from the server.
+ 
+ Connecting is done based on an identity or PKCS #12 data. The identity is an instance of `SecIdentityRef` and contains a certificate and private key. The PKCS #12 data can be deserialized into such an identity. One can reconnect or disconnect at any time, and should if the connection has been dropped by the server. The latter can happen quite easily, for example when there is something wrong with the device token or payload of the notification.
+ 
+ Notifications are pushed one at a time. It is serialized and sent over the wire. If the server then concludes there is something wrong with that notification, it will write back error data. If you send out multiple notifications in a row, these errors might not match up. Therefore every error contains the identifier of the erroneous notification.
+ 
+ Make sure to read this error data from the server, so you can lookup the notification that caused it and prevent the issue in the future. As mentioned earlier, the server easily drops the connection if there is something out of the ordinary. NB: if you read right after pushing, it is very unlikely that data about that push already got back from the server.
+ 
+ Make sure to read Apple's documentation on *Apple Push Notification Service* and *Provider Communication*.
+ */
 @interface NWPusher : NSObject
 
 /** @name Properties */

Classes/NWSSLConnection.h

@@ -9,7 +9,15 @@
 #import <Foundation/Foundation.h>
 
 
-/** Provides an interface to the SSL connection with APNS. `NWIdentityRef` represents a `SecIdentityRef`. Methods return `nil` or `NO` if an error occurred.
+/** An SSL (TLS) connection to the APNS server.
+
+ This class is basically an Objective-C wrapper around `SSLContextRef` and `SSLConnectionRef`, which are part of the native Secure Transport framework. This class provides a generic interface for SSL (TLS) connections, independent of NWPusher.
+ 
+ A SSL connection is set up using the host name, host port and an identity. The host name will be resolved using DNS. The identity is an instance of `SecIdentityRef` and contains both a certificate and a private key. See the *Secure Transport Reference* for more info on that.
+ 
+ Read more about provider communication in Apple's documentation under *Apple Push Notification Service*.
+ 
+ Methods return `NO` if an error occurred.
  */
 @interface NWSSLConnection : NSObject
 

Classes/NWSecTools.h

@@ -10,9 +10,7 @@
 
 /** A collection of tools for reading, converting and inspecting Keychain objects and PKCS #12 files.
 
- This is practically the glue that connects this framework to the Security framework and allows interacting with the OS Keychain and PKCS #12 files.
-
- `NWIdentityRef`, `NWCertificateRef` and `NWKeyRef` represent respectively `SecIdentityRef`, `SecCertificateRef`, `SecKeyRef`. Methods return `nil` or `NO` if an error occurred.
+ This is practically the glue that connects this framework to the Security framework and allows interacting with the OS Keychain and PKCS #12 files. It is mostly an Objective-C around the Security framework, including the benefits of ARC. `NWIdentityRef`, `NWCertificateRef` and `NWKeyRef` represent respectively `SecIdentityRef`, `SecCertificateRef`, `SecKeyRef`. It uses Cocoa-style error handling, so methods return `nil` or `NO` if an error occurred.
  */
 @interface NWSecTools : NSObject
 

Classes/NWType.h

@@ -144,7 +144,10 @@ typedef NS_ENUM(NSInteger, NWError) {
     kNWErrorKeychainCreateIdentity             = -303,
 };
 
-/** A collection of helper methods to support Cocoa-style error handling (NSError). */
+/** A collection of helper methods to support Cocoa-style error handling (`NSError`).
+ 
+ Most methods in this framework return `NO` or `nil` to indicate an error occurred. In that case an error object will be assigned. This class provides a mapping from codes to description string and some methods to instantiate the `NSError` object.
+ */
 @interface NWErrorUtil : NSObject
 
 /** @name Helpers */

README.md

@@ -32,11 +32,11 @@ Or simply include the source files you need. NWPusher has a modular architecture
 
 About
 -----
-Testing push notifications for your iOS app can be a pain. You might consider setting up your own server or use one of the many push webservices online. Either way it's a lot of work to get all these systems connected properly.
+Testing push notifications for your iOS or Mac app can be a pain. You might consider setting up your own server or use one of the many push webservices online. Either way it's a lot of work to get all these systems connected properly. When it is all working properly, push notifications come in fast (< 1 sec) and reliably. However when nothing comes in, it can be very hard to find out why.
 
-Enter *Pusher*, a Mac and iPhone app for sending push notifications *directly* to the *Apple Push Notification Service*. No need to set up a server or create an account online. You only need the SSL certificate and a device token to start pushing directly from your Mac, or even from an iPhone!
+That's why I made *Pusher*. It is a Mac and iPhone app for sending push notifications *directly* to the *Apple Push Notification Service*. No need to set up a server or create an account online. You only need the SSL certificate and a device token to start pushing directly from your Mac, or even from an iPhone! Pusher has detailed error reporting and logs, which are very helpful with verifying your setup.
 
-Pusher comes with a small framework for both OS X and iOS, that provides various tools for sending notifications programmatically. On OS X it can use the keychain to retrieve push certificates and keys. Pusher can also be used without keychain, using a PKCS #12 file.
+Pusher comes with a small framework for both OS X and iOS. It provides various tools for sending notifications programmatically. On OS X it can use the keychain to retrieve push certificates and keys. Pusher can also be used without keychain, using a PKCS #12 file. If you want to get a better understanding of how push notifications work, then this framework is a good place to start and play around.
 
 
 Features
@@ -53,6 +53,7 @@ Mac OS X application for sending push notifications through the APN service:
 
 OS X and iOS framework for sending pushes from your own application:
 - Modular, no dependencies, use what you like
+- Fully documented source code
 - Detailed error handling
 - iOS compatible, so you can also push directly from your iPhone :o
 - Demo applications for both platforms
@@ -351,7 +352,7 @@ Some tips on what to look out for:
 
 If it fails to connect then check:
 
-- Are the cerificates and keys in order? Use the OpenSSL commands listed above to inspect the cerificate. See if there is one push certificate and key present. Also make sure you're online, try `ping www.apple.com`.
+- Are the certificates and keys in order? Use the OpenSSL commands listed above to inspect the certificate. See if there is one push certificate and key present. Also make sure you're online, try `ping www.apple.com`.
 
 - Is the certificate properly loaded? Try initializing an identity using `[NWSecTools identityWithPKCS12Data:data password:password error:&error]` or `[NWSecTools keychainIdentityWithCertificate:certificate error:&error]`.