Correct doc

crates/libs/core/src/runtime/stateful.rs

@@ -188,7 +188,7 @@ pub trait LocalPrimaryReplicator: Replicator {
     /// begin to catchup. Idle secondary replicas are not included here.
     ///
     /// The total number of replica marked with must_catchup will not exceed the write quorum.
-    /// Secondary to be promoted to new primary is guaranteed to have must_catchup set at some point,
+    /// Secondary to be promoted to new primary is guaranteed to have must_catchup set,
     /// i.e. it must catch up (have all the data) to be promoted to new primary.
     ///
     /// ReplicaInformation:
@@ -211,16 +211,32 @@ pub trait LocalPrimaryReplicator: Replicator {
         currentconfiguration: &ReplicaSetConfig,
     ) -> crate::Result<()>;
 
-    /// Called on primary to wait for the quorum of replicas to catch up, before
+    /// Called on primary to wait for replicas to catch up, before
     /// accepting writes.
     ///
     /// mssf-core enables IFabricReplicatorCatchupSpecificQuorum for replicators,
     /// so ReplicaSetQuarumMode::Write can be used.
     ///
     /// catchupmode:
-    /// All -> full quorum, including all replicas.
-    /// Write -> write quorum, replicas specified in update_catch_up_replica_set_configuration(currentconfiguration...)
-    ///     with must_catchup set to true.
+    /// All -> full quorum. All replicas needs to catch up.
+    /// Write -> write quorum, for replicas specified in update_catch_up_replica_set_configuration(currentconfiguration...),
+    ///     a subset of replicas that can form a write quorum must catchup, and the subset must include
+    ///     the replica with must_catchup set to true (primary candidate).
+    ///     This is used only in primary swap case in SF, to avoid slow replica preventing/slowing down the swap.
+    /// Remarks:
+    /// Catchup (or quorum catchup) in SF means that the lowest LSN among all replicas (or quorum of replicas
+    /// including the must catchup replica) in the current configuration is equal or greater than
+    /// the current committed LSN.
+    ///
+    /// For swap primary case, double catchup feature is enabled by default.
+    /// SF can first call this api before initiating write status revokation. SF then revoke write status,
+    /// and call this again. This allows replicator to catch up with write status granted to make necessary writes for
+    /// catch up. There is a chance that replicator takes forever to complete this api with ReplicaSetQuarumMode::All
+    /// since client/user can keep writing and advancing the committed LSN, but for it most likely would not
+    /// stall ReplicaSetQuarumMode::Write.
+    ///
+    /// Implementor should not assume when this is called in relation to other api calls,
+    /// but instead follow the semantics of what catchup should do.
     async fn wait_for_catch_up_quorum(
         &self,
         catchupmode: ReplicaSetQuarumMode,
@@ -249,11 +265,12 @@ pub trait LocalPrimaryReplicator: Replicator {
         cancellation_token: CancellationToken,
     ) -> crate::Result<()>;
 
-    /// Notifies primary that an idle replica being built by build_replica() api call
+    /// Notifies primary that an idle replica built by build_replica() api call
     /// has gone down and replicator should not send more operations to that replica
     /// and should release all resources.
     /// Remarks:
     /// Removing replicas already in the partition, update_catch_up_replica_set_configuration
     /// is called instead with ReplicaSetConfig not containng the to be removed replica.
+    /// SF does not call remove_replica on the replica where build_replica is still running.
     fn remove_replica(&self, replicaid: i64) -> crate::Result<()>;
 }