Updating SyncManager documentation

components/sync_manager/src/manager.rs

@@ -117,6 +117,7 @@ impl SyncManager {
         Ok(())
     }
 
+    /// Disconnect engines from sync, deleting/resetting the sync-related data
     pub fn disconnect(&self) {
         if let Some(engine) = Self::places_engine("bookmarks") {
             if let Err(e) = engine.reset(&EngineSyncAssociation::Disconnected) {
@@ -155,6 +156,7 @@ impl SyncManager {
         }
     }
 
+    /// Perform a sync.  See [SyncParams] and [SyncResult] for details on how this works
     pub fn sync(&self, params: SyncParams) -> Result<SyncResult> {
         let mut state = self.mem_cached_state.lock().unwrap();
         let mut have_engines = vec![];

components/sync_manager/src/syncmanager.udl

@@ -18,12 +18,27 @@ enum SyncManagerError {
 };
 
 dictionary SyncParams {
+    // Why are we performing this sync?
     SyncReason reason;
+    // Which engines should we sync?
     SyncEngineSelection engines;
+    // Which engines should be enabled in the "account global" list (for
+    // example, if the UI was used to change an engine's state since the last
+    // sync).
     record<DOMString, boolean> enabled_changes;
+    // Keys to encrypt/decrypt data from local database files.  These are
+    // separate from the key we use to encrypt the sync payload as a whole.
     record<DOMString, string> local_encryption_keys;
+    // Authorization for the sync server
     SyncAuthInfo auth_info;
+    // An opaque string, as returned in the previous sync's SyncResult and
+    // persisted to disk, or null if no such state is available. This includes
+    // information such as the list of engines previously enabled, certain
+    // server timestamps and GUIDs etc. If this value isn't correctly persisted
+    // and round-tripped, each sync may look like a "first sync".
     string? persisted_state;
+    // Information about the current device, such as its name, formfactor and
+    // FxA device ID.
     DeviceSettings device_settings;
 };
 
@@ -63,12 +78,25 @@ enum DeviceType {
 };
 
 dictionary SyncResult {
+    // Result from the sync server
     ServiceStatus status;
-    record<DOMString, string> failures;
+    // Engines that synced successfully
     sequence<string> successful;
+    // Maps the names of engines that failed to sync to the reason why
+    record<DOMString, string> failures;
+    // State that should be persisted to disk and supplied to the sync method
+    // on the next sync (See SyncParams.persisted_state).
     string persisted_state;
+    // The list of engines which are marked as "declined" (ie, disabled) on the
+    // sync server. The list of declined engines is global to the account
+    // rather than to the device. Apps should use this after every sync to
+    // update the local state (ie, to ensure that their Sync UI correctly
+    // reflects what engines are enabled and disabled), because these could
+    // change after every sync.
     sequence<string>? declined;
+    // Earliest time that the next sync should happen at
     timestamp? next_sync_allowed_at;
+    // JSON string encoding a `SyncTelemetryPing` object
     string? telemetry_json;
 };
 
@@ -84,8 +112,10 @@ enum ServiceStatus {
 interface SyncManager {
     constructor();
 
+    // Disconnect engines from sync, deleting/resetting the sync-related data
     void disconnect();
 
+    // Perform a sync.  See [SyncParams] and [SyncResult] for details on how this works
     [Throws=SyncManagerError]
     SyncResult sync(SyncParams params);
 };

components/sync_manager/src/types.rs

@@ -4,12 +4,27 @@ use sync15::clients::DeviceType;
 
 #[derive(Debug)]
 pub struct SyncParams {
+    // Why are we performing this sync?
     pub reason: SyncReason,
+    // Which engines should we sync?
     pub engines: SyncEngineSelection,
+    // Which engines should be enabled in the "account global" list (for
+    // example, if the UI was used to change an engine's state since the last
+    // sync).
     pub enabled_changes: HashMap<String, bool>,
+    // Keys to encrypt/decrypt data from local database files.  These are
+    // separate from the key we use to encrypt the sync payload as a whole.
     pub local_encryption_keys: HashMap<String, String>,
+    // Authorization for the sync server
     pub auth_info: SyncAuthInfo,
+    // An opaque string, as returned in the previous sync's SyncResult and
+    // persisted to disk, or null if no such state is available. This includes
+    // information such as the list of engines previously enabled, certain
+    // server timestamps and GUIDs etc. If this value isn't correctly persisted
+    // and round-tripped, each sync may look like a "first sync".
     pub persisted_state: Option<String>,
+    // Information about the current device, such as its name, formfactor and
+    // FxA device ID.
     pub device_settings: DeviceSettings,
 }
 
@@ -45,12 +60,25 @@ pub struct DeviceSettings {
 
 #[derive(Debug)]
 pub struct SyncResult {
+    // Result from the sync server
     pub status: ServiceStatus,
-    pub failures: HashMap<String, String>,
+    // Engines that synced successfully
     pub successful: Vec<String>,
+    // Maps the names of engines that failed to sync to the reason why
+    pub failures: HashMap<String, String>,
+    // State that should be persisted to disk and supplied to the sync method
+    // on the next sync (See SyncParams.persisted_state).
     pub persisted_state: String,
+    // The list of engines which are marked as "declined" (ie, disabled) on the
+    // sync server. The list of declined engines is global to the account
+    // rather than to the device. Apps should use this after every sync to
+    // update the local state (ie, to ensure that their Sync UI correctly
+    // reflects what engines are enabled and disabled), because these could
+    // change after every sync.
     pub declined: Option<Vec<String>>,
+    // Earliest time that the next sync should happen at
     pub next_sync_allowed_at: Option<SystemTime>,
+    // JSON string encoding a `SyncTelemetryPing` object
     pub telemetry_json: Option<String>,
 }