From 3b361974dc2bcde4d028110a9a3e57b4a67a2695 Mon Sep 17 00:00:00 2001
From: rdb <git@rdb.name>
Date: Sun, 19 Jan 2020 11:22:53 +0100
Subject: [PATCH] actor: improve API documentation for Actor.cleanup()

Intended to address panda3d/panda3d-docs#40

[skip ci]
---
 direct/src/actor/Actor.py | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/direct/src/actor/Actor.py b/direct/src/actor/Actor.py
index 11d4990351..5b83df0d8c 100644
--- a/direct/src/actor/Actor.py
+++ b/direct/src/actor/Actor.py
@@ -500,7 +500,12 @@ class Actor(DirectObject, NodePath):
 
     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 @@ class Actor(DirectObject, NodePath):
             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 @@ class Actor(DirectObject, NodePath):
 
     def flush(self):
         """
-        Actor flush function
+        Actor flush function.  Used by `cleanup()`.
         """
         self.clearPythonData()