apollographql · designatednerd · Jul 22, 2019 · Jul 16, 2019 · Jul 16, 2019 · Jul 16, 2019
diff --git a/Sources/Apollo/GraphQLError.swift b/Sources/Apollo/GraphQLError.swift
@@ -29,7 +29,7 @@ public struct GraphQLError: Error {
     return (self["locations"] as? [JSONObject])?.compactMap(Location.init)
   }
 
-  /// A map which services can use however they see fit to provide additional information in errors to clients.
+  /// A dictionary which services can use however they see fit to provide additional information in errors to clients.
   public var extensions: [String : Any]? {
     return self["extensions"] as? [String : Any]
   }

diff --git a/Sources/Apollo/GraphQLExecutor.swift b/Sources/Apollo/GraphQLExecutor.swift
@@ -24,10 +24,14 @@ struct GraphQLResolveInfo {
   }
 }
 
+/// An error which has occurred in processing a GraphQLResult
 public struct GraphQLResultError: Error, LocalizedError {
   let path: ResponsePath
+
+  /// The error that occurred during parsing.
   public let underlying: Error
 
+  /// A description of the error which includes the path where the error occurred.
   public var errorDescription: String? {
     return "Error at path \"\(path))\": \(underlying)"
   }

diff --git a/docs/source/api-reference.md b/docs/source/api-reference.md
@@ -3,4 +3,77 @@ title: API Reference
 description: ''
 ---
 
-[Coming soon!]
+## [Apollo.framework](../api/Apollo/README/)
+## [ApolloSQLite.framework](../api/ApolloSQLite/README/)
+## [ApolloWebSocket.framework](../api/ApolloWebSocket/README/)
+
+Our API reference is automatically generated directly from the inline comments in our code, so if you're adding something new, all you have to do is actually add doc comments and they'll show up here. 
+
+See something missing documentation? Add docu-comments to the code, and open a pull request!
+
+To run the document generator, make sure you have [SourceDocs](https://github.com/eneko/SourceDocs) installed locally. The easiest way is via HomeBrew: 
+
+```
+brew install sourcedocs
+```
+
+>**NOTE**: We are currently depending on functionality added in [this PR](https://github.com/eneko/SourceDocs/pull/20), so if that's not merged, and pushed as a new version to Homebrew, you'll need to check out from source. 
+
+## Homebrew Instructions
+
+To generate docs for the main `Apollo` project, `cd` into the source root and run: 
+
+```
+sourcedocs generate \
+    --output-folder "docs/source/api/Apollo" \
+    --link-beginning "../" \
+    --link-ending "/" \
+    -- \
+    -scheme Apollo \
+    -workspace Apollo.xcworkspace
+```
+
+To generate docs for the `ApolloSQLite` project, `cd` into the source root and run: 
+
+```
+sourcedocs generate \
+    --output-folder "docs/source/api/ApolloSQLite" \
+    --link-beginning "../" \
+    --link-ending "/" \
+    -- \
+    -scheme ApolloSQLite \
+    -workspace Apollo.xcworkspace
+```
+
+To generate for docs the `ApolloWebSocket` project, `cd` into the source root and run: 
+
+```
+sourcedocs generate \
+    --output-folder "docs/source/api/ApolloWebSocket" \
+    --link-beginning "../" \
+    --link-ending "/" \
+    -- \
+    -scheme ApolloWebSocket \
+    -workspace Apollo.xcworkspace
+```
+
+## From Source Instructions
+
+Commands are essentially the same except for the following differences: 
+
+- All commands should start with `swift run sourcedocs` instead of just `sourcedocs`
+- Add an `--input-folder` parameter with the full path to the Apollo `SRCROOT` as its value
+- Make the value of `--output-folder`'s parameter use a full path rather than a relative one.
+
+For example, this will run the generator for `ApolloWebSocket`:
+
+``` 
+swift run sourcedocs generate \
+    --input-folder "/Users/[you]/apollo-ios" \
+    --output-folder "/Users/[you]/apollo-ios/docs/source/api/ApolloWebSocket" \
+    --link-beginning "../" \
+    --link-ending "/" \
+    -- \
+    -scheme "ApolloWebSocket" \
+    -workspace "Apollo.xcworkspace"
+```
diff --git a/docs/source/api/Apollo/README.md b/docs/source/api/Apollo/README.md
@@ -0,0 +1,103 @@
+## Protocols
+
+-   [Cancellable](../protocols/Cancellable/)
+-   [GraphQLFragment](../protocols/GraphQLFragment/)
+-   [GraphQLInputValue](../protocols/GraphQLInputValue/)
+-   [GraphQLMapConvertible](../protocols/GraphQLMapConvertible/)
+-   [GraphQLMutation](../protocols/GraphQLMutation/)
+-   [GraphQLOperation](../protocols/GraphQLOperation/)
+-   [GraphQLQuery](../protocols/GraphQLQuery/)
+-   [GraphQLSelection](../protocols/GraphQLSelection/)
+-   [GraphQLSelectionSet](../protocols/GraphQLSelectionSet/)
+-   [GraphQLSubscription](../protocols/GraphQLSubscription/)
+-   [HTTPNetworkTransportDelegate](../protocols/HTTPNetworkTransportDelegate/)
+-   [HTTPNetworkTransportPreflightDelegate](../protocols/HTTPNetworkTransportPreflightDelegate/)
+-   [HTTPNetworkTransportRetryDelegate](../protocols/HTTPNetworkTransportRetryDelegate/)
+-   [HTTPNetworkTransportTaskCompletedDelegate](../protocols/HTTPNetworkTransportTaskCompletedDelegate/)
+-   [JSONDecodable](../protocols/JSONDecodable/)
+-   [JSONEncodable](../protocols/JSONEncodable/)
+-   [Matchable](../protocols/Matchable/)
+-   [NetworkTransport](../protocols/NetworkTransport/)
+-   [NormalizedCache](../protocols/NormalizedCache/)
+
+## Structs
+
+-   [GraphQLBooleanCondition](../structs/GraphQLBooleanCondition/)
+-   [GraphQLError](../structs/GraphQLError/)
+-   [GraphQLField](../structs/GraphQLField/)
+-   [GraphQLFile](../structs/GraphQLFile/)
+-   [GraphQLFragmentSpread](../structs/GraphQLFragmentSpread/)
+-   [GraphQLHTTPResponseError](../structs/GraphQLHTTPResponseError/)
+-   [GraphQLResult](../structs/GraphQLResult/)
+-   [GraphQLResultError](../structs/GraphQLResultError/)
+-   [GraphQLTypeCase](../structs/GraphQLTypeCase/)
+-   [GraphQLTypeCondition](../structs/GraphQLTypeCondition/)
+-   [GraphQLVariable](../structs/GraphQLVariable/)
+-   [Location](../structs/Location/)
+-   [Record](../structs/Record/)
+-   [RecordSet](../structs/RecordSet/)
+-   [Reference](../structs/Reference/)
+
+## Classes
+
+-   [ApolloClient](../classes/ApolloClient/)
+-   [ApolloStore](../classes/ApolloStore/)
+-   [EmptyCancellable](../classes/EmptyCancellable/)
+-   [GraphQLQueryWatcher](../classes/GraphQLQueryWatcher/)
+-   [GraphQLResponse](../classes/GraphQLResponse/)
+-   [HTTPNetworkTransport](../classes/HTTPNetworkTransport/)
+-   [InMemoryNormalizedCache](../classes/InMemoryNormalizedCache/)
+-   [JSONSerializationFormat](../classes/JSONSerializationFormat/)
+-   [Promise](../classes/Promise/)
+-   [ReadTransaction](../classes/ReadTransaction/)
+-   [ReadWriteTransaction](../classes/ReadWriteTransaction/)
+
+## Enums
+
+-   [CachePolicy](../enums/CachePolicy/)
+-   [ErrorKind](../enums/ErrorKind/)
+-   [GraphQLHTTPRequestError](../enums/GraphQLHTTPRequestError/)
+-   [GraphQLOperationType](../enums/GraphQLOperationType/)
+-   [GraphQLOutputType](../enums/GraphQLOutputType/)
+-   [JSONDecodingError](../enums/JSONDecodingError/)
+-   [ResultOrPromise](../enums/ResultOrPromise/)
+-   [Source](../enums/Source/)
+
+## Extensions
+
+-   [Array](../extensions/Array/)
+-   [Bool](../extensions/Bool/)
+-   [Dictionary](../extensions/Dictionary/)
+-   [Double](../extensions/Double/)
+-   [Float](../extensions/Float/)
+-   [GraphQLError](../extensions/GraphQLError/)
+-   [GraphQLMapConvertible](../extensions/GraphQLMapConvertible/)
+-   [GraphQLMutation](../extensions/GraphQLMutation/)
+-   [GraphQLOperation](../extensions/GraphQLOperation/)
+-   [GraphQLQuery](../extensions/GraphQLQuery/)
+-   [GraphQLSelectionSet](../extensions/GraphQLSelectionSet/)
+-   [GraphQLSubscription](../extensions/GraphQLSubscription/)
+-   [GraphQLVariable](../extensions/GraphQLVariable/)
+-   [Int](../extensions/Int/)
+-   [JSONDecodingError](../extensions/JSONDecodingError/)
+-   [JSONEncodable](../extensions/JSONEncodable/)
+-   [Optional](../extensions/Optional/)
+-   [RawRepresentable](../extensions/RawRepresentable/)
+-   [Record](../extensions/Record/)
+-   [RecordSet](../extensions/RecordSet/)
+-   [Reference](../extensions/Reference/)
+-   [String](../extensions/String/)
+-   [URL](../extensions/URL/)
+
+## Methods
+
+-   [firstly(_:)](../methods/firstly(_:)/)
+-   [unzip(_:)](../methods/unzip(_:)/)
+-   [unzip(_:)](../methods/unzip(_:)/)
+-   [unzip(_:count:)](../methods/unzip(_:count:)/)
+-   [whenAll(_:notifyOn:)](../methods/whenAll(_:notifyOn:)/)
+-   [whenAll(_:notifyOn:)](../methods/whenAll(_:notifyOn:)/)
+
+# Reference Documentation
+This reference documentation was generated with
+[SourceDocs](https://github.com/eneko/SourceDocs).
diff --git a/docs/source/api/Apollo/classes/ApolloClient.md b/docs/source/api/Apollo/classes/ApolloClient.md
@@ -0,0 +1,166 @@
+**CLASS**
+
+# `ApolloClient`
+
+```swift
+public class ApolloClient
+```
+
+> The `ApolloClient` class provides the core API for Apollo. This API provides methods to fetch and watch queries, and to perform mutations.
+
+## Properties
+### `store`
+
+```swift
+public let store: ApolloStore
+```
+
+### `cacheKeyForObject`
+
+```swift
+public var cacheKeyForObject: CacheKeyForObject?
+```
+
+## Methods
+### `init(networkTransport:store:)`
+
+```swift
+public init(networkTransport: NetworkTransport, store: ApolloStore = ApolloStore(cache: InMemoryNormalizedCache()))
+```
+
+> Creates a client with the specified network transport and store.
+>
+> - Parameters:
+>   - networkTransport: A network transport used to send operations to a server.
+>   - store: A store used as a local cache. Defaults to an empty store backed by an in memory cache.
+
+#### Parameters
+
+| Name | Description |
+| ---- | ----------- |
+| networkTransport | A network transport used to send operations to a server. |
+| store | A store used as a local cache. Defaults to an empty store backed by an in memory cache. |
+
+### `init(url:)`
+
+```swift
+public convenience init(url: URL)
+```
+
+> Creates a client with an HTTP network transport connecting to the specified URL.
+>
+> - Parameter url: The URL of a GraphQL server to connect to.
+
+#### Parameters
+
+| Name | Description |
+| ---- | ----------- |
+| url | The URL of a GraphQL server to connect to. |
+
+### `clearCache()`
+
+```swift
+public func clearCache() -> Promise<Void>
+```
+
+> Clears apollo cache
+>
+> - Returns: Promise
+
+### `fetch(query:cachePolicy:context:queue:resultHandler:)`
+
+```swift
+@discardableResult public func fetch<Query: GraphQLQuery>(query: Query, cachePolicy: CachePolicy = .returnCacheDataElseFetch, context: UnsafeMutableRawPointer? = nil, queue: DispatchQueue = DispatchQueue.main, resultHandler: GraphQLResultHandler<Query.Data>? = nil) -> Cancellable
+```
+
+> Fetches a query from the server or from the local cache, depending on the current contents of the cache and the specified cache policy.
+>
+> - Parameters:
+>   - query: The query to fetch.
+>   - cachePolicy: A cache policy that specifies when results should be fetched from the server and when data should be loaded from the local cache.
+>   - queue: A dispatch queue on which the result handler will be called. Defaults to the main queue.
+>   - resultHandler: An optional closure that is called when query results are available or when an error occurs.
+> - Returns: An object that can be used to cancel an in progress fetch.
+
+#### Parameters
+
+| Name | Description |
+| ---- | ----------- |
+| query | The query to fetch. |
+| cachePolicy | A cache policy that specifies when results should be fetched from the server and when data should be loaded from the local cache. |
+| queue | A dispatch queue on which the result handler will be called. Defaults to the main queue. |
+| resultHandler | An optional closure that is called when query results are available or when an error occurs. |
+
+### `watch(query:cachePolicy:queue:resultHandler:)`
+
+```swift
+public func watch<Query: GraphQLQuery>(query: Query, cachePolicy: CachePolicy = .returnCacheDataElseFetch, queue: DispatchQueue = DispatchQueue.main, resultHandler: @escaping GraphQLResultHandler<Query.Data>) -> GraphQLQueryWatcher<Query>
+```
+
+> Watches a query by first fetching an initial result from the server or from the local cache, depending on the current contents of the cache and the specified cache policy. After the initial fetch, the returned query watcher object will get notified whenever any of the data the query result depends on changes in the local cache, and calls the result handler again with the new result.
+>
+> - Parameters:
+>   - query: The query to fetch.
+>   - fetchHTTPMethod: The HTTP Method to be used.
+>   - cachePolicy: A cache policy that specifies when results should be fetched from the server or from the local cache.
+>   - queue: A dispatch queue on which the result handler will be called. Defaults to the main queue.
+>   - resultHandler: An optional closure that is called when query results are available or when an error occurs.
+> - Returns: A query watcher object that can be used to control the watching behavior.
+
+#### Parameters
+
+| Name | Description |
+| ---- | ----------- |
+| query | The query to fetch. |
+| fetchHTTPMethod | The HTTP Method to be used. |
+| cachePolicy | A cache policy that specifies when results should be fetched from the server or from the local cache. |
+| queue | A dispatch queue on which the result handler will be called. Defaults to the main queue. |
+| resultHandler | An optional closure that is called when query results are available or when an error occurs. |
+
+### `perform(mutation:context:queue:resultHandler:)`
+
+```swift
+@discardableResult public func perform<Mutation: GraphQLMutation>(mutation: Mutation, context: UnsafeMutableRawPointer? = nil, queue: DispatchQueue = DispatchQueue.main, resultHandler: GraphQLResultHandler<Mutation.Data>? = nil) -> Cancellable
+```
+
+> Performs a mutation by sending it to the server.
+>
+> - Parameters:
+>   - mutation: The mutation to perform.
+>   - fetchHTTPMethod: The HTTP Method to be used.
+>   - queue: A dispatch queue on which the result handler will be called. Defaults to the main queue.
+>   - resultHandler: An optional closure that is called when mutation results are available or when an error occurs.
+> - Returns: An object that can be used to cancel an in progress mutation.
+
+#### Parameters
+
+| Name | Description |
+| ---- | ----------- |
+| mutation | The mutation to perform. |
+| fetchHTTPMethod | The HTTP Method to be used. |
+| queue | A dispatch queue on which the result handler will be called. Defaults to the main queue. |
+| resultHandler | An optional closure that is called when mutation results are available or when an error occurs. |
+
+### `subscribe(subscription:queue:resultHandler:)`
+
+```swift
+@discardableResult public func subscribe<Subscription: GraphQLSubscription>(subscription: Subscription, queue: DispatchQueue = DispatchQueue.main, resultHandler: @escaping GraphQLResultHandler<Subscription.Data>) -> Cancellable
+```
+
+> Subscribe to a subscription
+>
+> - Parameters:
+>   - subscription: The subscription to subscribe to.
+>   - fetchHTTPMethod: The HTTP Method to be used.
+>   - queue: A dispatch queue on which the result handler will be called. Defaults to the main queue.
+>   - resultHandler: An optional closure that is called when mutation results are available or when an error occurs.
+> - Returns: An object that can be used to cancel an in progress subscription.
+
+#### Parameters
+
+| Name | Description |
+| ---- | ----------- |
+| subscription | The subscription to subscribe to. |
+| fetchHTTPMethod | The HTTP Method to be used. |
+| queue | A dispatch queue on which the result handler will be called. Defaults to the main queue. |
+| resultHandler | An optional closure that is called when mutation results are available or when an error occurs. |