events: Document missing FolderWatchStateChanged (#745)

syncthing · Mar 15, 2022 · 8d51194 · 8d51194
1 parent 48a98f9
commit 8d51194
Showing 1 changed file with 21 additions and 0 deletions.
diff --git a/events/folderwatchstatechanged.rst b/events/folderwatchstatechanged.rst
@@ -0,0 +1,21 @@
+FolderWatchStateChanged
+-----------------------
+
+The ``FolderWatchStateChanged`` event is emitted when a folder's watcher routine
+encounters a new error, or when a previous error disappeared after retrying.
+The event contains the ID of the affected folder and textual error messages
+describing the previous (``from``) and the updated (``to``) error conditions.
+If there was no error in either of these, the respective field is omitted.
+
+.. code-block:: json
+
+    {
+      "id": 123,
+      "type": "FolderWatchStateChanged",
+      "time": "2022-03-14T12:34:56.890000000+01:00",
+      "data": {
+        "folder": "default",
+        "from": "Something bad happened.",
+        "to": "Something worse happened."
+      }
+    }