Update SceneBuffer to be less private and add docstring

Author: JasonGrace2282

manim/animation/scene_buffer.py

@@ -1,52 +1,61 @@
-from manim.mobject.opengl.opengl_mobject import OpenGLMobject as Mobject
+from typing import TYPE_CHECKING, final, Sequence
 
-from typing import final, Sequence
+if TYPE_CHECKING:
+    from manim.mobject.opengl.opengl_mobject import OpenGLMobject as Mobject
 
 
 __all__ = ["SceneBuffer"]
 
 
 @final
 class SceneBuffer:
+    """
+    A "buffer" between :class:`.Scene` and :class:`.Animation`
+
+    Operations an animation wants to do on :class:`.Scene` should be
+    done here (eg. :meth:`.Scene.add`, :meth:`.Scene.remove`). The
+    scene will then apply these changes at specific points (namely
+    at the beginning and end of animations)
+
+    It is the scenes job to clear the buffer in between the beginning
+    and end of animations.
+    """
+
     def __init__(self) -> None:
-        self.__to_remove: list[Mobject] = []
-        self.__to_add: list[Mobject] = []
+        self.to_remove: list[Mobject] = []
+        self.to_add: list[Mobject] = []
+        self.deferred = False
 
     def add(self, *mobs: Mobject) -> None:
         check_args(mobs)
-        self.__to_add.extend(mobs)
+        self._check_deferred()
+        self.to_add.extend(mobs)
 
     def remove(self, *mobs: Mobject) -> None:
         check_args(mobs)
-        self.__to_remove.extend(mobs)
+        self._check_deferred()
+        self.to_remove.extend(mobs)
 
     def clear(self) -> None:
-        self.__to_remove.clear()
-        self.__to_add.clear()
-
-    @property
-    def to_remove(self) -> tuple[Mobject, ...]:
-        return tuple(self.__to_remove)
+        self.to_remove.clear()
+        self.to_add.clear()
 
-    @to_remove.setter
-    def remove_mobject(self, mobs: Sequence[Mobject]) -> None:
-        check_args(mobs)
-        self.__to_remove = list(mobs)
-
-    @property
-    def to_add(self) -> tuple[Mobject, ...]:
-        return tuple(self.__to_add)
+    def deferred_clear(self) -> None:
+        """Clear ``self`` on next operation"""
+        self.deferred = True
 
-    @to_add.setter
-    def add_mobject(self, mobs: Sequence[Mobject]) -> None:
-        check_args(mobs)
-        self.__to_add = list(mobs)
+    def _check_deferred(self) -> None:
+        if self.deferred:
+            self.clear()
+            self.deferred = False
 
     def __str__(self) -> str:
-        to_add = self.__to_add
-        to_remove = self.__to_remove
+        to_add = self.to_add
+        to_remove = self.to_remove
         return f"{type(self).__name__}({to_add=}, {to_remove=})"
 
+    __repr__ = __str__
+
 
 def check_args(mobs: Sequence[Mobject]) -> None:
     if not (