From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sat, 23 Apr 2022 18:09:51 +0000 (+0100)
Subject: Document OccultOwningId serialisation and refcount rules
X-Git-Tag: otter-1.1.0~436
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=971b3c69a22794e7c8b87ce96bc5ad821e3353ce;p=otter.git

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 2a8a2ab7..487d79a7 100644
--- 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 eb005777..57772d85 100644
--- 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),