Skip to content

Commit ca19378

Browse files
designatednerddesignatednerd
authored
Merge pull request #642 from apollographql/add/markdown-docs
Auto-generate markdown documentation from inline docs
2 parents ee248a6 + c11c41c commit ca19378

96 files changed

Lines changed: 2713 additions & 2 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Sources/Apollo/GraphQLError.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ public struct GraphQLError: Error {
2929
return (self["locations"] as? [JSONObject])?.compactMap(Location.init)
3030
}
3131

32-
/// A map which services can use however they see fit to provide additional information in errors to clients.
32+
/// A dictionary which services can use however they see fit to provide additional information in errors to clients.
3333
public var extensions: [String : Any]? {
3434
return self["extensions"] as? [String : Any]
3535
}

‎Sources/Apollo/GraphQLExecutor.swift‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,14 @@ struct GraphQLResolveInfo {
2424
}
2525
}
2626

27+
/// An error which has occurred in processing a GraphQLResult
2728
public struct GraphQLResultError: Error, LocalizedError {
2829
let path: ResponsePath
30+
31+
/// The error that occurred during parsing.
2932
public let underlying: Error
3033

34+
/// A description of the error which includes the path where the error occurred.
3135
public var errorDescription: String? {
3236
return "Error at path \"\(path))\": \(underlying)"
3337
}

‎docs/source/api-reference.md‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,77 @@ title: API Reference
33
description: ''
44
---
55

6-
[Coming soon!]
6+
## [Apollo.framework](../api/Apollo/README/)
7+
## [ApolloSQLite.framework](../api/ApolloSQLite/README/)
8+
## [ApolloWebSocket.framework](../api/ApolloWebSocket/README/)
9+
10+
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.
11+
12+
See something missing documentation? Add docu-comments to the code, and open a pull request!
13+
14+
To run the document generator, make sure you have [SourceDocs](https://github.com/eneko/SourceDocs) installed locally. The easiest way is via HomeBrew:
15+
16+
```
17+
brew install sourcedocs
18+
```
19+
20+
>**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.
21+
22+
## Homebrew Instructions
23+
24+
To generate docs for the main `Apollo` project, `cd` into the source root and run:
25+
26+
```
27+
sourcedocs generate \
28+
--output-folder "docs/source/api/Apollo" \
29+
--link-beginning "../" \
30+
--link-ending "/" \
31+
-- \
32+
-scheme Apollo \
33+
-workspace Apollo.xcworkspace
34+
```
35+
36+
To generate docs for the `ApolloSQLite` project, `cd` into the source root and run:
37+
38+
```
39+
sourcedocs generate \
40+
--output-folder "docs/source/api/ApolloSQLite" \
41+
--link-beginning "../" \
42+
--link-ending "/" \
43+
-- \
44+
-scheme ApolloSQLite \
45+
-workspace Apollo.xcworkspace
46+
```
47+
48+
To generate for docs the `ApolloWebSocket` project, `cd` into the source root and run:
49+
50+
```
51+
sourcedocs generate \
52+
--output-folder "docs/source/api/ApolloWebSocket" \
53+
--link-beginning "../" \
54+
--link-ending "/" \
55+
-- \
56+
-scheme ApolloWebSocket \
57+
-workspace Apollo.xcworkspace
58+
```
59+
60+
## From Source Instructions
61+
62+
Commands are essentially the same except for the following differences:
63+
64+
- All commands should start with `swift run sourcedocs` instead of just `sourcedocs`
65+
- Add an `--input-folder` parameter with the full path to the Apollo `SRCROOT` as its value
66+
- Make the value of `--output-folder`'s parameter use a full path rather than a relative one.
67+
68+
For example, this will run the generator for `ApolloWebSocket`:
69+
70+
```
71+
swift run sourcedocs generate \
72+
--input-folder "/Users/[you]/apollo-ios" \
73+
--output-folder "/Users/[you]/apollo-ios/docs/source/api/ApolloWebSocket" \
74+
--link-beginning "../" \
75+
--link-ending "/" \
76+
-- \
77+
-scheme "ApolloWebSocket" \
78+
-workspace "Apollo.xcworkspace"
79+
```

‎docs/source/api/Apollo/README.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
## Protocols
2+
3+
- [Cancellable](../protocols/Cancellable/)
4+
- [GraphQLFragment](../protocols/GraphQLFragment/)
5+
- [GraphQLInputValue](../protocols/GraphQLInputValue/)
6+
- [GraphQLMapConvertible](../protocols/GraphQLMapConvertible/)
7+
- [GraphQLMutation](../protocols/GraphQLMutation/)
8+
- [GraphQLOperation](../protocols/GraphQLOperation/)
9+
- [GraphQLQuery](../protocols/GraphQLQuery/)
10+
- [GraphQLSelection](../protocols/GraphQLSelection/)
11+
- [GraphQLSelectionSet](../protocols/GraphQLSelectionSet/)
12+
- [GraphQLSubscription](../protocols/GraphQLSubscription/)
13+
- [HTTPNetworkTransportDelegate](../protocols/HTTPNetworkTransportDelegate/)
14+
- [HTTPNetworkTransportPreflightDelegate](../protocols/HTTPNetworkTransportPreflightDelegate/)
15+
- [HTTPNetworkTransportRetryDelegate](../protocols/HTTPNetworkTransportRetryDelegate/)
16+
- [HTTPNetworkTransportTaskCompletedDelegate](../protocols/HTTPNetworkTransportTaskCompletedDelegate/)
17+
- [JSONDecodable](../protocols/JSONDecodable/)
18+
- [JSONEncodable](../protocols/JSONEncodable/)
19+
- [Matchable](../protocols/Matchable/)
20+
- [NetworkTransport](../protocols/NetworkTransport/)
21+
- [NormalizedCache](../protocols/NormalizedCache/)
22+
23+
## Structs
24+
25+
- [GraphQLBooleanCondition](../structs/GraphQLBooleanCondition/)
26+
- [GraphQLError](../structs/GraphQLError/)
27+
- [GraphQLField](../structs/GraphQLField/)
28+
- [GraphQLFile](../structs/GraphQLFile/)
29+
- [GraphQLFragmentSpread](../structs/GraphQLFragmentSpread/)
30+
- [GraphQLHTTPResponseError](../structs/GraphQLHTTPResponseError/)
31+
- [GraphQLResult](../structs/GraphQLResult/)
32+
- [GraphQLResultError](../structs/GraphQLResultError/)
33+
- [GraphQLTypeCase](../structs/GraphQLTypeCase/)
34+
- [GraphQLTypeCondition](../structs/GraphQLTypeCondition/)
35+
- [GraphQLVariable](../structs/GraphQLVariable/)
36+
- [Location](../structs/Location/)
37+
- [Record](../structs/Record/)
38+
- [RecordSet](../structs/RecordSet/)
39+
- [Reference](../structs/Reference/)
40+
41+
## Classes
42+
43+
- [ApolloClient](../classes/ApolloClient/)
44+
- [ApolloStore](../classes/ApolloStore/)
45+
- [EmptyCancellable](../classes/EmptyCancellable/)
46+
- [GraphQLQueryWatcher](../classes/GraphQLQueryWatcher/)
47+
- [GraphQLResponse](../classes/GraphQLResponse/)
48+
- [HTTPNetworkTransport](../classes/HTTPNetworkTransport/)
49+
- [InMemoryNormalizedCache](../classes/InMemoryNormalizedCache/)
50+
- [JSONSerializationFormat](../classes/JSONSerializationFormat/)
51+
- [Promise](../classes/Promise/)
52+
- [ReadTransaction](../classes/ReadTransaction/)
53+
- [ReadWriteTransaction](../classes/ReadWriteTransaction/)
54+
55+
## Enums
56+
57+
- [CachePolicy](../enums/CachePolicy/)
58+
- [ErrorKind](../enums/ErrorKind/)
59+
- [GraphQLHTTPRequestError](../enums/GraphQLHTTPRequestError/)
60+
- [GraphQLOperationType](../enums/GraphQLOperationType/)
61+
- [GraphQLOutputType](../enums/GraphQLOutputType/)
62+
- [JSONDecodingError](../enums/JSONDecodingError/)
63+
- [ResultOrPromise](../enums/ResultOrPromise/)
64+
- [Source](../enums/Source/)
65+
66+
## Extensions
67+
68+
- [Array](../extensions/Array/)
69+
- [Bool](../extensions/Bool/)
70+
- [Dictionary](../extensions/Dictionary/)
71+
- [Double](../extensions/Double/)
72+
- [Float](../extensions/Float/)
73+
- [GraphQLError](../extensions/GraphQLError/)
74+
- [GraphQLMapConvertible](../extensions/GraphQLMapConvertible/)
75+
- [GraphQLMutation](../extensions/GraphQLMutation/)
76+
- [GraphQLOperation](../extensions/GraphQLOperation/)
77+
- [GraphQLQuery](../extensions/GraphQLQuery/)
78+
- [GraphQLSelectionSet](../extensions/GraphQLSelectionSet/)
79+
- [GraphQLSubscription](../extensions/GraphQLSubscription/)
80+
- [GraphQLVariable](../extensions/GraphQLVariable/)
81+
- [Int](../extensions/Int/)
82+
- [JSONDecodingError](../extensions/JSONDecodingError/)
83+
- [JSONEncodable](../extensions/JSONEncodable/)
84+
- [Optional](../extensions/Optional/)
85+
- [RawRepresentable](../extensions/RawRepresentable/)
86+
- [Record](../extensions/Record/)
87+
- [RecordSet](../extensions/RecordSet/)
88+
- [Reference](../extensions/Reference/)
89+
- [String](../extensions/String/)
90+
- [URL](../extensions/URL/)
91+
92+
## Methods
93+
94+
- [firstly(_:)](../methods/firstly(_:)/)
95+
- [unzip(_:)](../methods/unzip(_:)/)
96+
- [unzip(_:)](../methods/unzip(_:)/)
97+
- [unzip(_:count:)](../methods/unzip(_:count:)/)
98+
- [whenAll(_:notifyOn:)](../methods/whenAll(_:notifyOn:)/)
99+
- [whenAll(_:notifyOn:)](../methods/whenAll(_:notifyOn:)/)
100+
101+
# Reference Documentation
102+
This reference documentation was generated with
103+
[SourceDocs](https://github.com/eneko/SourceDocs).

‎docs/source/api/Apollo/classes/ApolloClient.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
**CLASS**
2+
3+
# `ApolloClient`
4+
5+
```swift
6+
public class ApolloClient
7+
```
8+
9+
> The `ApolloClient` class provides the core API for Apollo. This API provides methods to fetch and watch queries, and to perform mutations.
10+
11+
## Properties
12+
### `store`
13+
14+
```swift
15+
public let store: ApolloStore
16+
```
17+
18+
### `cacheKeyForObject`
19+
20+
```swift
21+
public var cacheKeyForObject: CacheKeyForObject?
22+
```
23+
24+
## Methods
25+
### `init(networkTransport:store:)`
26+
27+
```swift
28+
public init(networkTransport: NetworkTransport, store: ApolloStore = ApolloStore(cache: InMemoryNormalizedCache()))
29+
```
30+
31+
> Creates a client with the specified network transport and store.
32+
>
33+
> - Parameters:
34+
> - networkTransport: A network transport used to send operations to a server.
35+
> - store: A store used as a local cache. Defaults to an empty store backed by an in memory cache.
36+
37+
#### Parameters
38+
39+
| Name | Description |
40+
| ---- | ----------- |
41+
| networkTransport | A network transport used to send operations to a server. |
42+
| store | A store used as a local cache. Defaults to an empty store backed by an in memory cache. |
43+
44+
### `init(url:)`
45+
46+
```swift
47+
public convenience init(url: URL)
48+
```
49+
50+
> Creates a client with an HTTP network transport connecting to the specified URL.
51+
>
52+
> - Parameter url: The URL of a GraphQL server to connect to.
53+
54+
#### Parameters
55+
56+
| Name | Description |
57+
| ---- | ----------- |
58+
| url | The URL of a GraphQL server to connect to. |
59+
60+
### `clearCache()`
61+
62+
```swift
63+
public func clearCache() -> Promise<Void>
64+
```
65+
66+
> Clears apollo cache
67+
>
68+
> - Returns: Promise
69+
70+
### `fetch(query:cachePolicy:context:queue:resultHandler:)`
71+
72+
```swift
73+
@discardableResult public func fetch<Query: GraphQLQuery>(query: Query, cachePolicy: CachePolicy = .returnCacheDataElseFetch, context: UnsafeMutableRawPointer? = nil, queue: DispatchQueue = DispatchQueue.main, resultHandler: GraphQLResultHandler<Query.Data>? = nil) -> Cancellable
74+
```
75+
76+
> Fetches a query from the server or from the local cache, depending on the current contents of the cache and the specified cache policy.
77+
>
78+
> - Parameters:
79+
> - query: The query to fetch.
80+
> - cachePolicy: A cache policy that specifies when results should be fetched from the server and when data should be loaded from the local cache.
81+
> - queue: A dispatch queue on which the result handler will be called. Defaults to the main queue.
82+
> - resultHandler: An optional closure that is called when query results are available or when an error occurs.
83+
> - Returns: An object that can be used to cancel an in progress fetch.
84+
85+
#### Parameters
86+
87+
| Name | Description |
88+
| ---- | ----------- |
89+
| query | The query to fetch. |
90+
| cachePolicy | A cache policy that specifies when results should be fetched from the server and when data should be loaded from the local cache. |
91+
| queue | A dispatch queue on which the result handler will be called. Defaults to the main queue. |
92+
| resultHandler | An optional closure that is called when query results are available or when an error occurs. |
93+
94+
### `watch(query:cachePolicy:queue:resultHandler:)`
95+
96+
```swift
97+
public func watch<Query: GraphQLQuery>(query: Query, cachePolicy: CachePolicy = .returnCacheDataElseFetch, queue: DispatchQueue = DispatchQueue.main, resultHandler: @escaping GraphQLResultHandler<Query.Data>) -> GraphQLQueryWatcher<Query>
98+
```
99+
100+
> 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.
101+
>
102+
> - Parameters:
103+
> - query: The query to fetch.
104+
> - fetchHTTPMethod: The HTTP Method to be used.
105+
> - cachePolicy: A cache policy that specifies when results should be fetched from the server or from the local cache.
106+
> - queue: A dispatch queue on which the result handler will be called. Defaults to the main queue.
107+
> - resultHandler: An optional closure that is called when query results are available or when an error occurs.
108+
> - Returns: A query watcher object that can be used to control the watching behavior.
109+
110+
#### Parameters
111+
112+
| Name | Description |
113+
| ---- | ----------- |
114+
| query | The query to fetch. |
115+
| fetchHTTPMethod | The HTTP Method to be used. |
116+
| cachePolicy | A cache policy that specifies when results should be fetched from the server or from the local cache. |
117+
| queue | A dispatch queue on which the result handler will be called. Defaults to the main queue. |
118+
| resultHandler | An optional closure that is called when query results are available or when an error occurs. |
119+
120+
### `perform(mutation:context:queue:resultHandler:)`
121+
122+
```swift
123+
@discardableResult public func perform<Mutation: GraphQLMutation>(mutation: Mutation, context: UnsafeMutableRawPointer? = nil, queue: DispatchQueue = DispatchQueue.main, resultHandler: GraphQLResultHandler<Mutation.Data>? = nil) -> Cancellable
124+
```
125+
126+
> Performs a mutation by sending it to the server.
127+
>
128+
> - Parameters:
129+
> - mutation: The mutation to perform.
130+
> - fetchHTTPMethod: The HTTP Method to be used.
131+
> - queue: A dispatch queue on which the result handler will be called. Defaults to the main queue.
132+
> - resultHandler: An optional closure that is called when mutation results are available or when an error occurs.
133+
> - Returns: An object that can be used to cancel an in progress mutation.
134+
135+
#### Parameters
136+
137+
| Name | Description |
138+
| ---- | ----------- |
139+
| mutation | The mutation to perform. |
140+
| fetchHTTPMethod | The HTTP Method to be used. |
141+
| queue | A dispatch queue on which the result handler will be called. Defaults to the main queue. |
142+
| resultHandler | An optional closure that is called when mutation results are available or when an error occurs. |
143+
144+
### `subscribe(subscription:queue:resultHandler:)`
145+
146+
```swift
147+
@discardableResult public func subscribe<Subscription: GraphQLSubscription>(subscription: Subscription, queue: DispatchQueue = DispatchQueue.main, resultHandler: @escaping GraphQLResultHandler<Subscription.Data>) -> Cancellable
148+
```
149+
150+
> Subscribe to a subscription
151+
>
152+
> - Parameters:
153+
> - subscription: The subscription to subscribe to.
154+
> - fetchHTTPMethod: The HTTP Method to be used.
155+
> - queue: A dispatch queue on which the result handler will be called. Defaults to the main queue.
156+
> - resultHandler: An optional closure that is called when mutation results are available or when an error occurs.
157+
> - Returns: An object that can be used to cancel an in progress subscription.
158+
159+
#### Parameters
160+
161+
| Name | Description |
162+
| ---- | ----------- |
163+
| subscription | The subscription to subscribe to. |
164+
| fetchHTTPMethod | The HTTP Method to be used. |
165+
| queue | A dispatch queue on which the result handler will be called. Defaults to the main queue. |
166+
| resultHandler | An optional closure that is called when mutation results are available or when an error occurs. |

0 commit comments

Comments
 (0)
⚡