actor: improve API documentation for Actor.cleanup()

rdb · rdb · commit 3b361974dc2b · 2020-01-19T11:23:35.000+01:00
Intended to address panda3d/panda3d-docs#40 [skip ci]
diff --git a/direct/src/actor/Actor.py b/direct/src/actor/Actor.py
@@ -500,7 +500,12 @@ def pprint(self):
 
     def cleanup(self):
         """
-        Actor cleanup function
+        This method should be called when intending to destroy the Actor, and
+        cleans up any additional resources stored on the Actor class before
+        removing the underlying node using `removeNode()`.
+
+        Note that `removeNode()` itself is not sufficient to destroy actors,
+        which is why this method exists.
         """
         self.stop(None)
         self.clearPythonData()
@@ -512,6 +517,11 @@ def cleanup(self):
             self.removeNode()
 
     def removeNode(self):
+        """
+        You should call `cleanup()` for Actor objects instead, since
+        :meth:`~panda3d.core.NodePath.removeNode()` is not sufficient for
+        completely destroying Actor objects.
+        """
         if self.__geomNode and (self.__geomNode.getNumChildren() > 0):
             assert self.notify.warning("called actor.removeNode() on %s without calling cleanup()" % self.getName())
         NodePath.removeNode(self)
@@ -525,7 +535,7 @@ def clearPythonData(self):
 
     def flush(self):
         """
-        Actor flush function
+        Actor flush function.  Used by `cleanup()`.
         """
         self.clearPythonData()
 
