From f59a91a0dbdce7884b6c10affdcd0441c06d799d Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 16 Dec 2017 16:17:11 -0500 Subject: [PATCH] Add more warnings about Lua's delete() Closes #1170 --- docs/Lua API.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/Lua API.rst b/docs/Lua API.rst index a6a2ab8cd..520ac243a 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -125,12 +125,18 @@ All typed objects have the following built-in features: * ``ref:delete()`` - Destroys the object with the C++ ``delete`` operator. - If destructor is not available, returns *false*. + Destroys the object with the C++ ``delete`` operator. If the destructor is not + available, returns *false*. (This typically only occurs when trying to delete + an instance of a DF class with virtual methods whose vtable address has not + been found; it is impossible for ``delete()`` to determine the validity of + ``ref``.) .. warning:: - the lua reference object remains as a dangling - pointer, like a raw C++ pointer would. + ``ref`` **must** be an object allocated with ``new``, like in C++. Calling + ``obj.field:delete()`` where ``obj`` was allocated with ``new`` will not + work. After ``delete()`` returns, ``ref`` remains as a dangling pointer, + like a raw C++ pointer would. Any accesses to ``ref`` after ``ref:delete()`` + has been called are undefined behavior. * ``ref:assign(object)``