 
 // MARK: - MockableResponse
 
+/// Defined an interface for mocking data task result data for a given request.
 public protocol MockableDataTaskResult {
+    /**
+     Returns data that will be passed to the data task's completion handler
+     - parameter request: The request that the data task result is responding to.
+     - returns: Data that will be passed to the completion handler of the task.
+    */
     func dataTaskResult(request: URLRequestEncodable) -> (NSData?, NSURLResponse?, NSError?)
 }
 
 // MARK: - MockResponse
 
+/// Encapsulates the meta and body data of a response.
 public struct MockResponse {
     enum Error: ErrorType {
         case InvalidURL
     }
     
+    /// HTTP status code.
     public let statusCode: Int
+ 
+    /// Response body data
     public var data: NSData?
+    
+    /// Response URL
     public var url: NSURL?
+    
+    /// HTTP header fields
     public var headers: [String : String]?
+    
+    /// Version of the HTTP response as represented by the server. Typically this is represented as "HTTP/1.1".
     public var version: String?
     
+    /// Create a mock response with a given status code.
     public init(statusCode: Int) {
         self.statusCode = statusCode
     }
     
+    /// Create a mock response with a status code and response body data.
     public init(statusCode: Int, data: NSData) {
         self.init(statusCode: statusCode)
         self.data = data
     }
     
-    /// Defines a stubbed JSON object to use as the stubbed response body data.
+    /// Create a mocked response with a  JSON object to use as the stubbed response body data.
     public init(statusCode: Int, json: AnyObject) {
         self.init(statusCode: statusCode)
         self.data = try? NSJSONSerialization.dataWithJSONObject(json, options: NSJSONWritingOptions(rawValue: 0))

    
    // MARK: Stubbing API
    
    public func addStub(response: MockableDataTaskResult, requestMatcher: (URLRequestEncodable) -> (Bool)) {
        stubs.append((response, requestMatcher))
    }
    
    public func addStub(response: MockableDataTaskResult) {
        stubs.append((response, { _ in return true}))
    }
    
    public func stubbedResponse(request request: URLRequestEncodable) -> (NSData?, NSURLResponse?, NSError?) {
        for (response, matcher) in stubs.reverse() where matcher(request) {
            return response.dataTaskResult(request)


// MARK: - MockSession

/// Implements the `Session` protocol and provides an API for adding mocked responses as stubs.
public class MockSession: Session {
    typealias Stub = (MockableDataTaskResult, (URLRequestEncodable) -> (Bool))
    lazy var stubs = [Stub]()
