Merge pull request #1297 from remotestorage/docs/1289-sync_events

Document sync event callback arguments

CHANGELOG.md

@@ -1,33 +1,7 @@
 # remoteStorage.js Changelog
 
-All releases can also be found and downloaded on the [releases page][1] on GitHub.
-
-## 2.0.0 (January 2022)
-
-### Breaking changes
-
-* Remove Bower package support (#1231)
-* Minimum sync interval is now 2000ms (#1260)
-
-### Enhancements
-
-* Convert source code to TypeScript (#1175, #1196, #1199, #1211, #1214, #1233, #1239, #1249)
-* Update dependencies (#1206, #1226)
-* Switch from Travis CI to GitHub Actions (#1223, #1224, #1225)
-* Don't add trailing slash as only pathname to redirect_uri param (#1213)
-* BaseClient#getObject: Throw error instead of string when JSON parsing fails (#1215)
-* Improve documentation (#1219, #1227, #1241, #1242)
-* Make ReadTheDocs work with current node.js/npm, TypeDoc, etc. (#1220, #1230)
-* Don't include unnecessary files in npm package (#1232)
-* Improve validation of custom sync interval settings (#1260)
-* Allow to connect via URL (#1250)
-
-### Bugfixes
-
-* Fix WireClient initialization when localStorage settings data corrupted/missing (#1210)
-* Handle Google Drive paths with special characters (#1181)
-* Fix potentially wrong command in warning message (#1218)
-* Don't list trashed files in GDrive folder listings (#1257)
+The changelogs for releases from version 2.0 onwards can be found on the
+[Releases page][1] on GitHub.
 
 ## 1.2.3 (January 2020)
 

doc/js-api/remotestorage.rst

@@ -117,12 +117,44 @@ List of events
 
 ``sync-req-done``
 """""""""""""""""
-   Emitted when a single sync request has finished
+   Emitted when a single sync request has finished. Callback functions
+   receive an object as argument, informing the client of remaining items
+   in the current sync task queue.
+
+   Example::
+
+      remoteStorage.on('sync-req-done', result => console.log(result));
+
+      // { tasksRemaining: 21 }
+
+   .. NOTE::
+      The internal task queue holds at most 100 items at the same time,
+      regardless of the overall amount of items to sync. Therefore, this number
+      is only an indicator of sync status, not a precise amount of items left
+      to sync. It can be useful to determine if your app should display any
+      kind of sync status/progress information for the cycle or not.
 
 ``sync-done``
 """""""""""""
-   Emitted when all tasks of a sync have been completed and a new sync
-   is scheduled
+   Emitted when a sync cycle has been completed and a new sync is scheduled.
+
+   The callback function receives an object as argument, informing the client
+   if the sync process has completed successfully or not.
+
+   Example::
+
+      remoteStorage.on('sync-done', result => console.log(result));
+
+      // { completed: true }
+
+   If ``completed`` is ``false``, it means that some of the sync requests have
+   failed and will be retried in the next sync cycle (usually a few seconds
+   later in this case). This is not an unusual scenario on mobile networks or
+   when doing a large initial sync for example.
+
+   For an app's user interface, you may want to consider the sync process as
+   ongoing in this case, and wait until your app sees a positive ``completed``
+   status before updating the UI.
 
 ``network-offline``
 """""""""""""""""""