From 6b93c4cc691e7ca0ec3e3073b6f91439706f59f7 Mon Sep 17 00:00:00 2001
From: Benoit Germain <benoit.germain@ubisoft.com>
Date: Wed, 11 Dec 2024 10:36:35 +0100
Subject: Remove documentation wrongitudes

---
 docs/index.html | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/index.html b/docs/index.html
index 8bb181f..bfa2615 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1893,15 +1893,15 @@ class MyDeepFactory : public DeepFactory
 static MyDeepFactory g_MyDeepFactory;
 </pre></td></tr></table>
 		<ul>
-			<li><tt>newDeepObjectInternal</tt>: requests the creation of a new object, whose pointer is returned. Said object must derive from <tt>DeepPrelude</tt>.</li>
-			<li><tt>deleteDeepObjectInternal</tt>: should cleanup the object.</li>
-			<li><tt>createMetatable</tt>: should build a metatable for the object. Don't cache the metatable yourself, Lanes takes care of it (<tt>createMetatable</tt> should only be invoked once per state). Just push the metatable on the stack.</li>
-			<li><tt>moduleName</tt>: requests the name of the module that exports the factory, to be returned. It is necessary so that Lanes can require it in any lane state that receives a userdata. This is to prevent crashes in situations where the module could be unloaded while the factory pointer is still held.</li>
+			<li><tt>newDeepObjectInternal()</tt>: requests the creation of a new object, whose pointer is returned. Said object must derive from <tt>DeepPrelude</tt>.</li>
+			<li><tt>deleteDeepObjectInternal()</tt>: should cleanup the object.</li>
+			<li><tt>createMetatable()</tt>: should build a metatable for the object. Don't cache the metatable yourself, Lanes takes care of it (<tt>createMetatable</tt> should only be invoked once per state). Just push the metatable on the stack.</li>
+			<li><tt>moduleName()</tt>: requests the name of the module that exports the factory, to be returned. It is necessary so that Lanes can require it in any lane state that receives a userdata. This is to prevent crashes in situations where the module could be unloaded while the factory pointer is still held.</li>
 		</ul>
 		Take a look at <tt>LindaFactory</tt> in <tt>lindafactory.cpp</tt> or <tt>MyDeepFactory</tt> in <tt>deep_test.cpp</tt>.
 	</li>
 	<li>Include <tt>"_pch.hpp", "deep.hpp"</tt> and either link against Lanes or statically compile <tt>compat.cpp deep.cpp</tt> into your module if you want to avoid a runtime dependency for users that will use your module without Lanes.
-	<li>Instanciate your userdata using <tt>yourFactoryObject.pushDeepUserdata()</tt>, instead of the regular <tt>lua_newuserdata()</tt>. Given a <tt>factory</tt>, it sets up the support structures and returns a state-specific proxy userdata for accessing your data. This proxy can also be copied over to other lanes.</li>
+	<li>Instanciate your userdata using <tt>yourFactoryObject.pushDeepUserdata()</tt>, instead of the regular <tt>lua_newuserdata()</tt>. Given a <tt>factory</tt>, it sets up the support structures and returns a state-specific proxy full userdata for accessing your data. This proxy can also be copied over to other lanes.</li>
 	<li>Accessing the deep userdata from your C code, use <tt>yourFactoryObject.toDeep()</tt> instead of the regular <tt>lua_touserdata()</tt>.</li>
 	<li>To push an existing proxy on the stack, use <tt>DeepPrelude::push(L)</tt>.</li>
 </ol>
@@ -1911,10 +1911,8 @@ static MyDeepFactory g_MyDeepFactory;
 </p>
 
 <p>
-	Deep userdata in transit inside <a href="#keepers">Keeper states</a> (sent in a <a href="#lindas">linda</a> but not yet consumed) don't call <tt>deleteDeepObjectInternal</tt> and aren't considered by reference counting. The rationale is the following:<br />
-	If some non-keeper state holds a deep userdata for some deep object, then even if the keeper collects its own deep userdata, it shouldn't be cleaned up since the refcount is not 0.<br />
-	OTOH, if a keeper state holds the last deep userdata for some deep object, then no lane can do actual work with it. Deep userdata's <tt>factory()</tt> interface is never accessed from a keeper state.<br />
-	Therefore, Lanes can just call <tt>deleteDeepObjectInternal</tt> when the last non-keeper-held deep userdata is collected, as long as it doesn't do the same in a keeper state after that, since any remaining deep userdata in <a href="#keepers">Keeper states</a> now hold stale pointers.
+	Pay attention to the fact a deep userdata last proxy can be held inside a Keeper state after being stored in a Linda and all other references are lost.
+	If the Linda then flushes its contents through garbage collection in the Keeper state or by being collected itself, it means that <tt>deleteDeepObjectInternal()</tt> can be called from inside a Keeper state.
 </p>
 
 <p>
-- 
cgit v1.2.3-55-g6feb