Added Docstring/Example for :meth:always_redraw (#3312)

* Added docstring & example for always_redraw

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* made more descriptive names for vars in example

* Change runtime 10s->3s

Co-authored-by: Jason Villanueva <[email protected]>

* change Create -> add

Co-authored-by: Benjamin Hackl <[email protected]>

* Added typehint for always_redraw

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Changed description of :meth:`always_redraw`

Co-authored-by: Benjamin Hackl <[email protected]>

* Added return type to :meth:`always_redraw`

Co-authored-by: Benjamin Hackl <[email protected]>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Jason Villanueva <[email protected]>
Co-authored-by: Benjamin Hackl <[email protected]>

Author: 4 people

manim/animation/updaters/mobject_update_utils.py

@@ -15,6 +15,7 @@
 
 
 import inspect
+from collections.abc import Callable
 
 import numpy as np
 
@@ -55,9 +56,46 @@ def updater(mob):
     return mobject
 
 
-def always_redraw(func):
+def always_redraw(func: Callable[[], Mobject]) -> Mobject:
+    """Redraw the mobject constructed by a function every frame.
+
+    This function returns a mobject with an attached updater that
+    continuously regenerates the mobject according to the
+    specified function.
+
+    Parameters
+    ----------
+    func
+        A function without (required) input arguments that returns
+        a mobject.
+
+    Examples
+    --------
+
+    .. manim:: TangentAnimation
+
+        class TangentAnimation(Scene):
+            def construct(self):
+                ax = Axes()
+                sine = ax.plot(np.sin, color=RED)
+                alpha = ValueTracker(0)
+                point = always_redraw(
+                        lambda: Dot(
+                            sine.point_from_proportion(alpha.get_value()),
+                            color=BLUE)
+                    )
+                tangent = always_redraw(
+                    lambda: TangentLine(
+                        sine,
+                        alpha=alpha.get_value(),
+                        color=YELLOW,
+                        length=4)
+                )
+                self.add(ax, sine, point, tangent)
+                self.play(alpha.animate.set_value(1), rate_func=linear, run_time=2)
+    """
     mob = func()
-    mob.add_updater(lambda m: mob.become(func()))
+    mob.add_updater(lambda _: mob.become(func()))
     return mob