Add documentation about using GraphQLQueryWatcher with mutations (#543)

apollo-ios/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

docs/source/fetching/queries.mdx

@@ -23,7 +23,7 @@ let watcher = apollo.watch(query: HeroNameQuery()) { result in
 }
 ```
 
-If any of the data for the query changes in the local cache, the result handler will be invoked again.
+If your query shares response objects with other operations you will need to implement a [normalized cache](../caching/introduction.mdx) so that object data received in those other operations is written to the local cache and used to update your query watcher by invoking the result handler.
 
 When you call `ApolloClient.watch(query:)` a [`GraphQLQueryWatcher`](https://www.apollographql.com/docs/ios/docc/documentation/apollo/graphqlquerywatcher) is returned. Changes to the query's data will be watched until `cancel()` is called on the watcher.