docs: add docstring to docref watch

firestore/docref.go

@@ -795,7 +795,8 @@ type DocumentSnapshotIterator struct {
 // the current state of the document. If the document has been deleted, Next
 // returns a DocumentSnapshot whose Exists method returns false.
 //
-// Next never returns iterator.Done unless it is called after Stop.
+// Next is not expected to return iterator.Done unless it is called after Stop.
+// Rarely, networking issues may also cause iterator.Done to be returned.
 func (it *DocumentSnapshotIterator) Next() (*DocumentSnapshot, error) {
 	btree, _, readTime, err := it.ws.nextSnapshot()
 	if err != nil {

firestore/watch.go

@@ -163,6 +163,7 @@ func (s *watchStream) nextSnapshot() (*btree.BTree, []DocumentChange, time.Time,
 		for !s.handleNextMessage() {
 		}
 		if s.err != nil {
+			// NOTE: Seems this is probably the close that cusutomers are seeing?
 			_ = s.close() // ignore error
 			return nil, nil, time.Time{}, s.err
 		}
@@ -225,6 +226,7 @@ func (s *watchStream) handleNextMessage() bool {
 			s.resetDocs() // Remove all the current results.
 			// The filter didn't match; close the stream so it will be re-opened on the next
 			// call to nextSnapshot.
+			// NOTE: could also be this one.
 			_ = s.close() // ignore error
 			s.lc = nil
 		}