Improve Mobject.align_data docstring

manim/mobject/mobject.py

@@ -2705,7 +2705,7 @@ def construct(self):
 
     # Alignment
     def align_data(self, mobject: Mobject, skip_point_alignment: bool = False) -> None:
-        """Aligns the data of this mobject with another mobject.
+        """Aligns the family structure and data of this mobject with another mobject.
 
         Afterwards, the two mobjects will have the same number of submobjects
         (see :meth:`.align_submobjects`), the same parent structure (see
@@ -2719,6 +2719,31 @@ def align_data(self, mobject: Mobject, skip_point_alignment: bool = False) -> No
         skip_point_alignment
             Controls whether or not the computationally expensive
             point alignment is skipped (default: False).
+
+
+        .. note::
+
+            This method is primarily used internally by :meth:`.become` and the
+            :class:`~.Transform` animation to ensure that mobjects are structurally
+            compatible before transformation.
+
+        Examples
+        --------
+        ::
+
+            >>> from manim import Rectangle, Line, ORIGIN, RIGHT
+            >>> rect = Rectangle(width=4.0, height=2.0, grid_xstep=1.0, grid_ystep=0.5)
+            >>> line = Line(start=ORIGIN,end=RIGHT)
+            >>> line.align_data(rect)
+            >>> len(line.get_family()) == len(rect.get_family())
+            True
+            >>> line.get_num_points() == rect.get_num_points()
+            True
+
+        See also
+        --------
+        :class:`~.Transform`, :meth:`~.Mobject.become`, :meth:`~.VMobject.align_points`, :meth:`~.Mobject.get_family`
+
         """
         self.null_point_align(mobject)
         self.align_submobjects(mobject)
@@ -2943,6 +2968,10 @@ def construct(self):
             >>> result = rect.copy().become(circ, match_center=True)
             >>> np.allclose(rect.get_center(), result.get_center())
             True
+
+        See also
+        --------
+        :meth:`~.Mobject.align_data`, :meth:`~.VMobject.interpolate_color`
         """
         mobject = mobject.copy()
         if stretch: