Update docs/source/contributing/docs/types.rst

Author: chopan050

docs/source/contributing/docs/types.rst

@@ -22,32 +22,46 @@ in space. For example:
 
 .. code-block:: python
 
-   def status2D(coord: Point2D) -> None:
+   def print_point2D(coord: Point2DLike) -> None:
        x, y = coord
        print(f"Point at {x=},{y=}")
 
 
-   def status3D(coord: Point3D) -> None:
+   def print_point3D(coord: Point3DLike) -> None:
        x, y, z = coord
        print(f"Point at {x=},{y=},{z=}")
 
 
-   def get_statuses(coords: Point2D_Array | Point3D_Array) -> None:
+   def print_point_array(coords: Point2DLike_Array | Point3DLike_Array) -> None:
        for coord in coords:
            if len(coord) == 2:
-               # it's a Point2D
-               status2D(coord)
+               # it's a Point2DLike
+               print_point2D(coord)
            else:
-               # it's a point3D
-               status3D(coord)
-
-It's important to realize that the status functions accepted both
-tuples/lists of the correct length, and ``NDArray``'s of the correct shape.
-If they only accepted ``NDArray``'s, we would use their ``Internal`` counterparts:
-:class:`~.typing.InternalPoint2D`, :class:`~.typing.InternalPoint3D`, :class:`~.typing.InternalPoint2D_Array` and :class:`~.typing.InternalPoint3D_Array`.
-
-In general, the type aliases prefixed with ``Internal`` should never be used on
-user-facing classes and functions, but should be reserved for internal behavior.
+               # it's a Point3DLike
+               print_point3D(coord)
+
+   def shift_point_up(coord: Point3DLike) -> Point3D:
+       result = np.asarray(coord)
+       result += UP
+       return result
+
+Notice that the last function, ``shift_point_up()``, accepts a
+:class:`~.Point3DLike` as a parameter and returns a :class:`~.Point3D`. A
+:class:`~.Point3D` always represents a NumPy array consisting of 3 floats,
+whereas a :class:`~.Point3DLike` can represent anything resembling a 3D point:
+either a NumPy array or a tuple/list of 3 floats, hence the ``Like`` word. The
+same happens with :class:`~.Point2D`, :class:`~.Point2D_Array` and
+:class:`~.Point3D_Array`, and their ``Like`` counterparts
+:class:`~.Point2DLike`, :class:`~.Point2DLike_Array` and
+:class:`~.Point3DLike_Array`.
+
+The rule for typing functions is: **make parameter types as broad as possible,
+and return types as specific as possible.** Therefore, for functions which are
+intended to be called by users, we should always, if possible, accept ``Like``
+types as parameters and return NumPy, non-``Like`` types. The last function,
+``shift_point_up()``, is an example of it. Internal functions which are *not*
+meant to be called by users may accept non-``Like`` parameters if necessary.
 
 Vectors
 ~~~~~~~