OpOutcomeThunk: Rationalise doc comment

Most of this comment is from earlier thoughts about how to solve the
problme that fastsplit now solves, and much of it wasn't really right.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/src/updates.rs b/src/updates.rs
index db2780af2953f59eabaab423976663df969eb8c7..b6ef27748092c4d60ab19dc87fd5c9d3920ed24d 100644 (file)
--- a/src/updates.rs
+++ b/src/updates.rs
@@ -172,30 +172,10 @@ pub enum OpOutcomeThunk {
   ///
   /// Use with care!  Eg, you might have to call save_game_and_aux_late.r
   ///
-  /// Rules for adding and removing pieces:
-  ///
-  ///  * Adding a piece: add it to both ipieces and pieces.
-  ///    Call `save_game_and_aux_later`.
-  ///    Aux is always saved first, so if the piece is in pieces,
-  ///    it will be in ipieces on any reload.
-  ///
-  ///  * Deleting a piece: if the deletion as not the result of
-  ///    some kind of merge, and it doesn't matter if only the
-  ///    deletion happens, and not other recent events: just delete it.
-  ///    Call `save_game_and_aux_later`.
-  ///
-  ///  * Deleting a piece, in some kind of more complicated situation
-  ///    where the deletion must be atomic with other operations.
-  ///    Delete the piece *only* from pieces.  Leave it in ipieces.
-  ///    A reload will always restore a `GameState` snapshot.
-  ///    TODO: we should garbage-collect the slot in ipieces.
-  ///
-  /// TODO: Provide `&mut InstanceGuard` to the closure,
-  ///       not `&umut Instance`, since the latter is not sufficient.
-  ///
-  /// TODO: Provide cooked methods for this (taking `ModifyingPieces`)
-  ///
-  /// TODO: Provide a `ModifyingPieces` to the closure.
+  /// Adding and removing pieces during play (rather than management)
+  /// is complicated, because we want to avoid having to rewrite the aux.
+  /// file during routine game saves.  `fastsplit.rs` has machinery that
+  /// can achieve this.
   Reborrow(Box<dyn FnOnce(&mut InstanceGuard, PlayerId, PieceId)
                    -> Result<UpdateFromOpComplex, ApiPieceOpError>>),
 }