Squashed 'apollo-ios/' changes from e7abd715..7e1c45b7

7e1c45b7 Add documentation about using GraphQLQueryWatcher with mutations (#543)

git-subtree-dir: apollo-ios
git-subtree-split: 7e1c45b74dfd75f1667a4312f73d547667dd61a0

Sources/Apollo/GraphQLQueryWatcher.swift

@@ -3,9 +3,14 @@ import Foundation
 import ApolloAPI
 #endif
 
-/// A `GraphQLQueryWatcher` is responsible for watching the store, and calling the result handler with a new result whenever any of the data the previous result depends on changes.
+/// A `GraphQLQueryWatcher` is responsible for watching the store, and calling the result handler with a new result
+/// whenever any of the data the previous result depends on changes. If your query shares response objects with other
+/// operations you should read about normalizing objects by cache key in our documentation. Normalized objects will
+/// update all query watchers that had received that object before.
 ///
-/// NOTE: The store retains the watcher while subscribed. You must call `cancel()` on your query watcher when you no longer need results. Failure to call `cancel()` before releasing your reference to the returned watcher will result in a memory leak.
+/// NOTE: The store retains the watcher while subscribed. You must call `cancel()` on your query watcher when you no
+/// longer need results. Failure to call `cancel()` before releasing your reference to the returned watcher will
+/// result in a memory leak.
 public final class GraphQLQueryWatcher<Query: GraphQLQuery>: Cancellable, ApolloStoreSubscriber {
   weak var client: (any ApolloClientProtocol)?
   public let query: Query