Document OccultOwningId serialisation and refcount rules

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

diff --git a/src/global.rs b/src/global.rs
index 2a8a2ab71cd395fa1c3fd2fcce207f7b996a67d2..487d79a72aa174d1012d2dd554b8f0d7834355e2 100644 (file)
--- a/src/global.rs
+++ b/src/global.rs
@@ -77,6 +77,7 @@ pub struct IPlayer { // usual variable: ipl
 }
 
 #[derive(Debug,Serialize,Deserialize)]
+/// Strange ownership and serialisation rules, like `OccultIlkOwningId`
 pub struct IPiece {
   pub p: IPieceTraitObj,
   pub occilk: Option<IOccultIlk>,

diff --git a/src/occultilks.rs b/src/occultilks.rs
index eb00577706e8eca4d90b45f914bc01d2f725e4fd..57772d8555ddfddf3838ac6ffd6936591a749fc7 100644 (file)
--- a/src/occultilks.rs
+++ b/src/occultilks.rs
@@ -7,6 +7,13 @@ use crate::prelude::*;
 slotmap::new_key_type!{ pub struct OccultIlkId; }
 
 /// Does *not* `impl Drop`.  Don't just drop it.
+///
+/// Must be serialized *only* in aux (ig, Instance) *not* GameState!
+/// Otherwise refcount could be inconsistent.
+///
+/// Barring such errors, the refcount in an Instance's IOccultIlks
+/// will be the count of OccultIlkOwningIds elsewhere in the Instance,
+/// and the same will go for the saved aux file.
 #[derive(Debug,Serialize,Deserialize)]
 #[serde(transparent)]
 pub struct OccultIlkOwningId(Id);
@@ -39,7 +46,10 @@ pub enum LOccultIlk {
 }
 
 serde_with_compat!{
-  [ #[derive(Debug,Serialize,Deserialize)] ]
+  [ 
+    /// Strange ownership and serialisation rules, like `OccultIlkOwningId`
+    #[derive(Debug,Serialize,Deserialize)]
+  ]
   [ pub ][ enum ] IOccultIlk="IOccultIlk" IOccultIlk_New "IOccultIlk_Compat" [
     {
       Distinct(OccultIlkData),