Issues in Transform docs?

[ubaldot]

The docs of Transform are a bit confusing.

The current signature in the docs is:

class Transform(mobject=None, *args, use_override=True, **kwargs)

but then the following list of parameters does not really match:

PARAMETERS:

- mobject ([Mobject](https://docs.manim.community/en/stable/reference/manim.mobject.mobject.Mobject.html#manim.mobject.mobject.Mobject) | None) – The [Mobject](https://docs.manim.community/en/stable/reference/manim.mobject.mobject.Mobject.html#manim.mobject.mobject.Mobject) to be transformed. It will be mutated to become the target_mobject.

- target_mobject ([Mobject](https://docs.manim.community/en/stable/reference/manim.mobject.mobject.Mobject.html#manim.mobject.mobject.Mobject) | None) – The target of the transformation.

- path_func (Callable | None) – A function defining the path that the points of the mobject are being moved along until they match the points of the target_mobject, see [utils.paths](https://docs.manim.community/en/stable/reference/manim.utils.paths.html#module-manim.utils.paths).

- path_arc (float) – The arc angle (in radians) that the points of mobject will follow to reach the points of the target if using a circular path arc, see path_arc_centers. See also [manim.utils.paths.path_along_arc()](https://docs.manim.community/en/stable/reference/manim.utils.paths.html#manim.utils.paths.path_along_arc).

- path_arc_axis (np.ndarray) – The axis to rotate along if using a circular path arc, see path_arc_centers.

- path_arc_centers (np.ndarray) –

The center of the circular arcs along which the points of mobject are moved by the transformation.

If this is set and path_func is not set, then a path_along_circles path will be generated using the path_arc parameters and stored in path_func. If path_func is set, this and the other path_arc fields are set as attributes, but a path_func is not generated from it.

- replace_mobject_with_target_in_scene (bool) –

Controls which mobject is replaced when the transformation is complete.

If set to True, mobject will be removed from the scene and target_mobject will replace it. Otherwise, target_mobject is never added and mobject just takes its shape.

[MrDiver]

does it not ? it's everything that can be passed to *args and **kwargs 🤷🏼

[ubaldot]

does it not ?

Not at all.

class Transform(mobject:Mobject, target_mobject:Mobject,  path_func: Callable = ???, path_arc:float = ??? , path_arc_axis:np.ndarray = ???, path_arc_centers:np.ndarray = ???, **kwargs)

Transforms mobject into target_mobject. 

PARAMETERS:

- mobject ([Mobject](https://docs.manim.community/en/stable/reference/manim.mobject.mobject.Mobject.html#manim.mobject.mobject.Mobject)) – The [Mobject](https://docs.manim.community/en/stable/reference/manim.mobject.mobject.Mobject.html#manim.mobject.mobject.Mobject) to be transformed. It will be mutated to become the target_mobject.

- target_mobject ([Mobject](https://docs.manim.community/en/stable/reference/manim.mobject.mobject.Mobject.html#manim.mobject.mobject.Mobject)) – The target of the transformation.

- path_func (Callable) – A function defining the path that the points of the mobject are being moved along until they match the points of the target_mobject, see [utils.paths](https://docs.manim.community/en/stable/reference/manim.utils.paths.html#module-manim.utils.paths).

- path_arc (float) – The arc angle (in radians) that the points of mobject will follow to reach the points of the target if using a circular path arc, see path_arc_centers. See also [manim.utils.paths.path_along_arc()](https://docs.manim.community/en/stable/reference/manim.utils.paths.html#manim.utils.paths.path_along_arc).

- path_arc_axis (np.ndarray) – The axis to rotate along if using a circular path arc, see path_arc_centers.

- path_arc_centers (np.ndarray) – The center of the circular arcs along which the points of mobject are moved by the transformation.

- **kwargs - keyword arguments passed to the parent class Animation.

> NOTE: If this is set and path_func is not set, then a path_along_circles path will be generated using the path_arc parameters and stored in path_func. If path_func is set, this and the other path_arc fields are set as attributes, but a path_func is not generated from it.

In-spite there are many tweaks to be done (like the ???'s and perhaps something to be fixed here and there), from a user perspective I bet that the wide majority would find this version more clear compared to what is currently in the docs.

Even semantically: if Transform(A, B) is intended to transform A into B, it must require at least two positional arguments. The fact that "under the hood" you could call Transform(None) has no utility for the user. What does it mean semantically? What the user shall expect after this? It is just confusing overhead that produce zero value (actually it produces "negative" value, i.e. confusion).

Shall this issue really be closed?

[behackl]

The parameter documentation is correct, the signature in the function header is a bug that comes from implementing Animation.__new__, I believe. This is a minor thing, but it should be fixed.