From c9d7feccfa954e2ed7d0a28b5d961eaa958691f3 Mon Sep 17 00:00:00 2001
From: Michele Caini <michele.caini@gmail.com>
Date: Wed, 2 Oct 2024 10:46:14 +0200
Subject: [PATCH] doc: more about the reactive mixin

---
 TODO              |  2 --
 docs/md/entity.md | 23 +++++++++++++++++------
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/TODO b/TODO
index 8af2b8914..62c45a59d 100644
--- a/TODO
+++ b/TODO
@@ -40,6 +40,4 @@ TODO:
 * refine the storage fallback mechanism for views (ie alloc?)
 * sigh_mixin: automatic signal registration
 * sigh_mixin: change cb signature from reg/entt to storage/entt (breaking for the good)
-* reactive_mixin: note about no-auto-disconnect mechanism
-* reactive_mixin: in-code and md doc about callback signature
 * don't pass reactive storage by default to callback
diff --git a/docs/md/entity.md b/docs/md/entity.md
index f91644982..9fb5419ff 100644
--- a/docs/md/entity.md
+++ b/docs/md/entity.md
@@ -489,8 +489,8 @@ storage.bind(registry);
 
 In this case, it must be provided with a reference registry for subsequent
 operations.<br/>
-Alternatively, when using the value type provided directly by `EnTT`, it's also
-possible to create a reactive storage directly inside a registry:
+Alternatively, when using the value type provided by `EnTT`, it's also possible
+to create a reactive storage directly inside a registry:
 
 ```cpp
 entt::registry registry{};
@@ -622,10 +622,21 @@ for(auto [entity, pos]: storage.view<position>(entt::exclude<velocity>).each())
 The registry used in this case is the one associated with the storage and also
 available via the `registry` function.
 
-Finally, it should be noted that a reactive storage never deletes its entities
-(and elements, if any).<br/>
-To process and then discard entities at regular intervals, refer to the `clear`
-function available by default for each storage type.
+It should be noted that a reactive storage never deletes its entities (and
+elements, if any). To process and then discard entities at regular intervals,
+refer to the `clear` function available by default for each storage type.<br/>
+Similarly, the reactive mixin doesn't disconnect itself from observed storages
+upon destruction. Therefore, users have to do this themselves:
+
+```cpp
+entt::registry = storage.registry();
+
+registry.on_construct<position>().disconnect(&storage);
+registry.on_construct<velocity>().disconnect(&storage);
+```
+
+Destroying a reactive storage without disconnecting it from observed pools will
+result in undefined behavior.
 
 ## Sorting: is it possible?