 
 import Foundation
 
-/// Public type for capabilities
-public struct Capability { }
-
-// MARK: CapabilityType
-
+/**
+
+ # CapabilityType
+ 
+ This is the high level definition for device/user/system
+ capabilities which typically would require the user's
+ permission to access. For example, location, calendars,
+ photos, health kit etc.
+*/
+public protocol CapabilityType {
+
+    /// A type which performs the registration of capability permissions.
+    typealias Registrar: CapabilityRegistrarType
+
+    /// A type which indicates the current status of the capability
+    typealias Status: AuthorizationStatusType
+
+    /// - returns: a String, the name of the capability
+    var name: String { get }
+
+    /**
+     A requirement of the capability. This is generic, and it
+     allows for granuality in the capabilities permissions.
+     For example, with Location, we either request a "when in use"
+     or "always" permission.
+     
+     - returns: the necessary Status.Requirement
+    */
+    var requirement: Status.Requirement { get }
+
+    /**
+     Initialize a new capability with the requirement and a registrar.
+     
+     Implementations should provide a default registrar - it is here
+     to support injection & unit testing.
+
+     - parameter requirement: the needed Status.Requirement
+     - parameter registrar: the registrar item.
+    */
+    init(_ requirement: Status.Requirement, registrar: Registrar)
+
+    /**
+     Query the capability to see if it's available on the device.
+     
+     - returns: true Bool value if the capability is available.
+    */
+    func isAvailable() -> Bool
+
+    /**
+     Get the current authorization status of the capability. This
+     can be performed asynchronously. The status is returns as the
+     argument to a completion block.
+     
+     - parameter completion: a Status -> Void closure.
+    */
+    func authorizationStatus(completion: Status -> Void)
+
+    /**
+     Request authorization with the requirement of the capability.
+     
+     Again, this is designed to be performed asynchronously. More than
+     likely the registrar will present a dialog and wait for the user.
+     When control is returned, the completion block should be called.
+     
+     - parameter completion: a dispatch_block_t closure.
+    */
+    func requestAuthorizationWithCompletion(completion: dispatch_block_t)
+}
+
+/**
+ A protocol to define the authorization status of a device
+ capability. Typically this will be an enum, like 
+ CLAuthorizationStatus. Note that it is itself generic over
+ the Requirement. This allows for another (or existing) enum 
+ to be used to define granular levels of permissions. Use Void
+ if not needed.
+*/
 public protocol AuthorizationStatusType {
     typealias Requirement
 
+    /**
+     Given the current authorization status (i.e. self)
+     this function should determine whether or not the
+     provided Requirement has been met or not. Therefore
+     this function should consider the overall authorization
+     state, and if *authorized* - whether the authorization 
+     is enough for the Requirement.
+     
+     - see: CLAuthorizationStatus extension for example.
+     
+     - parameter requirement: the necessary Requirement
+     - returns: a Bool indicating whether or not the requirements are met.
+    */
     func isRequirementMet(requirement: Requirement) -> Bool
 }
 
+/**
+ Protocol for the underlying capabiltiy registrar.
+*/
 public protocol CapabilityRegistrarType {
+
+    /// The only requirement is that it can be initialized with
+    /// no parameters.
     init()
 }
 
-public protocol CapabilityType {
-    typealias Registrar: CapabilityRegistrarType
-    typealias Status: AuthorizationStatusType
-
-    var name: String { get }
-    var requirement: Status.Requirement { get }
-
-    init(_ requirement: Status.Requirement, registrar: Registrar)
-    func isAvailable() -> Bool
-    func authorizationStatus(completion: Status -> Void)
-    func requestAuthorizationWithCompletion(completion: dispatch_block_t)
-}
+/**
+ Capability is a namespace to nest as aliases the
+ various device capability types.
+ */
+public struct Capability { }
+
 
 extension Capability {
 
+    /**
+     Some device capabilities might not have the need for
+     an authorization level, but still might not be available. For example
+     PassKit. In which case, use VoidStatus as the nested Status type.
+    */
     public struct VoidStatus: AuthorizationStatusType {
         public func isRequirementMet(requirement: Void) -> Bool {
             return true

    }
}

// MARK: - Operations

public class GetAuthorizationStatus<Capability: CapabilityType>: Operation {

    public typealias StatusResponse = (Bool, Capability.Status)
    public typealias Completion = StatusResponse -> Void

    public var isAvailable: Bool? = .None
    public var status: Capability.Status? = .None

    let capability: Capability
    let completion: Completion

    public init(_ capability: Capability, completion: Completion = { _ in }) {
        self.capability = capability
        self.completion = completion

        }
    }

    /// The execute function required by Operation
    public override func execute() {
        determineState { response in
            self.completion(response)
