More implementation comments in QueryInfo cache.watch listener.

Author: benjamn

src/core/QueryInfo.ts

@@ -229,14 +229,23 @@ export class QueryInfo {
     if (oq) {
       oq["queryInfo"] = this;
       this.listeners.add(this.oqListener = () => {
-        // If this.diff came from an optimistic transaction, deliver the current
-        // cache data to the ObservableQuery, but don't perform a reobservation,
-        // since oq.reobserveCacheFirst might make a network request, and we
-        // don't want to trigger network requests for optimistic updates.
         const diff = this.getDiff();
         if (diff.fromOptimisticTransaction) {
+          // If this diff came from an optimistic transaction, deliver the
+          // current cache data to the ObservableQuery, but don't perform a
+          // reobservation, since oq.reobserveCacheFirst might make a network
+          // request, and we never want to trigger network requests in the
+          // middle of optimistic updates.
           oq["observe"]();
         } else {
+          // Otherwise, make the ObservableQuery "reobserve" the latest data
+          // using a temporary fetch policy of "cache-first", so complete cache
+          // results have a chance to be delivered without triggering additional
+          // network requests, even when options.fetchPolicy is "network-only"
+          // or "cache-and-network". All other fetch policies are preserved by
+          // this method, and are handled by calling oq.reobserve(). If this
+          // reobservation is spurious, isDifferentFromLastResult still has a
+          // chance to catch it before delivery to ObservableQuery subscribers.
           oq.reobserveCacheFirst();
         }
       });