update a ton of documentation

Author: designatednerd

Sources/Apollo/ApolloErrorInterceptor.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// An error interceptor called to allow further examination of error data when an error occurs in the chain.
 public protocol ApolloErrorInterceptor {
 
   /// Asynchronously handles the receipt of an error at any point in the chain.

Sources/Apollo/ApolloInterceptor.swift

@@ -1,5 +1,13 @@
+/// A protocol to set up a chainable unit of networking work.
 public protocol ApolloInterceptor: class {
 
+  /// Called when this interceptor should do its work.
+  ///
+  /// - Parameters:
+  ///   - chain: The chain the interceptor is a part of.
+  ///   - request: The request, as far as it has been constructed
+  ///   - response: The response, as far as it has been constructed
+  ///   - completion: The completion block to fire when data needs to be returned to the UI.
   func interceptAsync<ParsedValue: Parseable, Operation: GraphQLOperation>(
     chain: RequestChain,
     request: HTTPRequest<Operation>,

Sources/Apollo/FinalizingInterceptor.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// The last interceptor in a normal chain, which checks that parsing has been completed and returns information to the UI.
 public class FinalizingInterceptor: ApolloInterceptor {
 
   enum FinalizationError: Error {

Sources/Apollo/HTTPResponse.swift

@@ -1,10 +1,17 @@
 import Foundation
 
+/// Data about a response received by an HTTP request.
 public class HTTPResponse<ParsedValue: Parseable> {
   public var httpResponse: HTTPURLResponse?
   public var rawData: Data?
   public var parsedResponse: ParsedValue?
 
+  /// Designated initializer
+  ///
+  /// - Parameters:
+  ///   - response: [optional] The `HTTPURLResponse` received from the server. Will be nil if not yet received or if the response received was not an `HTTPURLResponse`.
+  ///   - rawData: [optional] The raw, unparsed data received from the server. Will be nil if not yet received or if data received from the server was nil.
+  ///   - parsedResponse: [optional] The response parsed into the `ParsedValue` type. Will be nil if not yet received, not yet parsed, or if parsing failed.
   public init(response: HTTPURLResponse?,
               rawData: Data?,
               parsedResponse: ParsedValue?) {

Sources/Apollo/InterceptorProvider.swift

@@ -2,6 +2,7 @@ import Foundation
 
 // MARK: - Basic protocol
 
+/// A protocol to allow easy creation of an array of interceptors for a given operation.
 public protocol InterceptorProvider {
 
   /// Creates a new array of interceptors when called
@@ -12,14 +13,17 @@ public protocol InterceptorProvider {
 
 // MARK: - Default implementation for typescript codegen
 
+/// The default interceptor provider for typescript-generated code
 public class LegacyInterceptorProvider: InterceptorProvider {
 
   private let client: URLSessionClient
   private let store: ApolloStore
 
   /// Designated initializer
   ///
-  /// - Parameter client: The URLSession client to use. Defaults to the default setup.
+  /// - Parameters:
+  ///   - client: The `URLSessionClient` to use. Defaults to the default setup.
+  ///   - store: The `ApolloStore` to use when reading from or writing to the cache.
   public init(client: URLSessionClient = URLSessionClient(),
               store: ApolloStore) {
     self.client = client
@@ -40,6 +44,8 @@ public class LegacyInterceptorProvider: InterceptorProvider {
 
 // MARK: - Default implementation for swift codegen
 
+
+/// The default interceptor proider for code generated with Swift Codegen™
 public class CodableInterceptorProvider<FlexDecoder: FlexibleDecoder>: InterceptorProvider {
 
   private let client: URLSessionClient

Sources/Apollo/JSONRequest.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// A request which sends JSON related to a GraphQL operation.
 public class JSONRequest<Operation: GraphQLOperation>: HTTPRequest<Operation> {
 
   public let requestCreator: RequestCreator

Sources/Apollo/LegacyCacheReadInterceptor.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// An interceptor that reads data from the legacy cache for queries, following the `HTTPRequest`'s `cachePolicy`.
 public class LegacyCacheReadInterceptor: ApolloInterceptor {
 
   public enum CacheReadError: Error {
@@ -8,6 +9,9 @@ public class LegacyCacheReadInterceptor: ApolloInterceptor {
 
   private let store: ApolloStore
 
+  /// Designated initializer
+  ///
+  /// - Parameter store: The store to use when reading from the cache.
   public init(store: ApolloStore) {
     self.store = store
   }
@@ -55,7 +59,7 @@ public class LegacyCacheReadInterceptor: ApolloInterceptor {
         self.fetchFromCache(for: request, chain: chain) { cacheFetchResult in
           switch cacheFetchResult {
           case .failure:
-            // Cache miss, proceed to network without calling completion
+            // Cache miss, proceed to network without returning error
             chain.proceedAsync(request: request,
                                response: response,
                                completion: completion)

Sources/Apollo/LegacyCacheWriteInterceptor.swift

@@ -1,9 +1,13 @@
 import Foundation
 
+/// An interceptor which writes data to the legacy cache, following the `HTTPRequest`'s `cachePolicy`.
 public class LegacyCacheWriteInterceptor: ApolloInterceptor {
 
   public let store: ApolloStore
 
+  /// Designated initializer
+  ///
+  /// - Parameter store: The store to use when writing to the cache.
   public init(store: ApolloStore) {
     self.store = store
   }

Sources/Apollo/LegacyParsingInterceptor.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// An interceptor which parses code using the legacy parsing system.
 public class LegacyParsingInterceptor: ApolloInterceptor {
 
   public func interceptAsync<ParsedValue: Parseable, Operation: GraphQLOperation>(

Sources/Apollo/NetworkFetchInterceptor.swift

@@ -1,10 +1,14 @@
 import Foundation
 
-public class NetworkFetchInterceptor: ApolloInterceptor {
+/// An interceptor which actually fetches data from the network.
+public class NetworkFetchInterceptor: ApolloInterceptor, Cancellable {
   let client: URLSessionClient
   private var currentTask: URLSessionTask?
 
-  init(client: URLSessionClient) {
+  /// Designated initializer.
+  ///
+  /// - Parameter client: The `URLSessionClient` to use to fetch data
+  public init(client: URLSessionClient) {
     self.client = client
   }
 
@@ -46,4 +50,8 @@ public class NetworkFetchInterceptor: ApolloInterceptor {
       }
     }
   }
+  
+  public func cancel() {
+    self.currentTask?.cancel()
+  }
 }