 
 // MARK: - UI
 
+/**
+A protocol which defines the presentation API used for `UIOperation`. This is mostly to provide testability.
+*/
 public protocol PresentingViewController: class {
+
+    /**
+    Presents the view controller.
+
+    - parameter viewController: the `UIViewController` being presented.
+    - parameter animated: a `Bool` flag to indicate whether the presentation should be animated.
+    - parameter completion: a completion block which may be nil.
+    */
     func presentViewController(viewController: UIViewController, animated: Bool, completion: (() -> Void)?)
 
+
     @available(iOS 8.0, *)
+    /**
+    Shows the view controller.
+
+    - parameter vc: the `UIViewController` being presented.
+    - parameter sender: an optional `AnyObject`, usually this is a `UIControl`.
+    */
     func showViewController(vc: UIViewController, sender: AnyObject?)
 
     @available(iOS 8.0, *)
+    /**
+    Shows the view controller as a detail controller in a split view controller.
+
+    - parameter vc: the `UIViewController` being presented.
+    - parameter sender: an optional `AnyObject`, usually this is a `UIControl`.
+    */
     func showDetailViewController(vc: UIViewController, sender: AnyObject?)
 }
 
 extension UIViewController: PresentingViewController { }
 
+/**
+A simple enum to convey how a view controller should be presented. The view controller
+which performs the presentation is stored as an associated type, and is generic. So, 
+to present a detail view controller from a master view controller say, it would be
+used like this
+
+    let from: ViewControllerDisplayStyle = .ShowDetail(masterViewController)
+    from.displayController(detailViewController, sender: .None, completion: .None)
+
+This enum is used as an argument for the `UIOperation` class which usually is 
+responsible for creating the view controller which is to be presented.
+*/
 public enum ViewControllerDisplayStyle<ViewController: PresentingViewController> {
 
     case Show(ViewController)
     case ShowDetail(ViewController)
     case Present(ViewController)
 
+    /// Access the associated view controller.
     public var controller: ViewController {
         switch self {
         case .Show(let controller):

    }
}

public enum UIOperationError: ErrorType {
    case PresentationViewControllerNotSet
}

public class UIOperation<C, From where C: UIViewController, From: PresentingViewController>: Operation {

    public let controller: C
    public let from: ViewControllerDisplayStyle<From>
    public let sender: AnyObject?
    let completion: (() -> Void)?

    public init(controller: C, displayControllerFrom from: ViewControllerDisplayStyle<From>, sender: AnyObject? = .None, completion: (() -> Void)? = .None) {
        self.controller = controller
        self.from = from

        self.completion = completion
    }

    /**
    When the operation executes, on the main queue, it calls `displayController` on the
    ViewControllerDisplayStyle, which in turn will execute either `presentViewController`, 
    `showViewController`, or `showDetailViewController`.
    */
    public override func execute() {
        dispatch_async(Queue.Main.queue) {
            self.from.displayController(self.controller, sender: self.sender, completion: self.completion)
