From e4aea701ab6bb586663d15233f4f8749fba103df Mon Sep 17 00:00:00 2001
From: Erik Johnston <erikj@matrix.org>
Date: Fri, 23 Sep 2016 09:57:06 +0100
Subject: [PATCH] Comment

---
 lib/sync.js | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/lib/sync.js b/lib/sync.js
index dea2feb28..e4086a994 100644
--- a/lib/sync.js
+++ b/lib/sync.js
@@ -549,6 +549,12 @@ SyncApi.prototype._sync = function(syncOptions) {
             // This is the first failure, which may be spurious. To avoid unnecessary
             // connection error warnings we simply retry the /sync immediately. Only
             // if *that* one fails too do we say the connection has been lost.
+            // Examples of when this may happen are:
+            //   - Restarting backend servers. (In an HA world backends may be
+            //     restarted all the time, and its easiest just to make the
+            //     client retry).
+            //   - Intermediate proxies restarting.
+            //   - Device network changes.
             // Should we emit a state like "MAYBE_CONNETION_LOST"?
             self._syncConnectionLost = true;
             self._sync(syncOptions);