Add missing docstrings

arcade/camera/data_types.py

@@ -44,6 +44,16 @@ class CameraData:
     """Stores position, orientation, and zoom for a camera.
 
     This is like where a camera is placed in 3D space.
+
+    Args:
+        position:
+            The camera's location in 3D space.
+        up:
+            The direction which is considered "up" for the camera.
+        forward:
+            The direction the camera is facing.
+        zoom:
+            How much the camera is zoomed in or out.
     """
 
     __slots__ = ("position", "up", "forward", "zoom")
@@ -56,19 +66,23 @@ def __init__(
         zoom: float = 1.0,
     ):
 
-        #: A 3D vector which describes where the camera is located.
         self.position: tuple[float, float, float] = position
-        #: A 3D vector which describes which direction is up (+y).
+        """A 3D vector which describes where the camera is located."""
+
         self.up: tuple[float, float, float] = up
-        #: A scalar which describes which direction the camera is pointing.
-        #:
-        #: While this affects the projection matrix, it also allows camera
-        #: controllers to access zoom functionality without interacting with
-        #: projection data.
+        """A 3D vector which describes which direction is up (+y)."""
+
         self.forward: tuple[float, float, float] = forward
+        """
+        A scalar which describes which direction the camera is pointing.
+
+        While this affects the projection matrix, it also allows camera
+        controllers to access zoom functionality without interacting with
+        projection data.
+        """
 
-        # Zoom
         self.zoom: float = zoom
+        """A scalar which describes how much the camera is zoomed in or out."""
 
     def __str__(self):
         return f"CameraData<{self.position=}, {self.up=}, {self.forward=}, {self.zoom=}>"
@@ -78,6 +92,12 @@ def __repr__(self):
 
 
 def duplicate_camera_data(origin: CameraData):
+    """
+    Clone camera data
+
+    Args:
+        origin: The camera data to clone
+    """
     return CameraData(origin.position, origin.up, origin.forward, float(origin.zoom))
 
 
@@ -109,30 +129,44 @@ class OrthographicProjectionData:
     right, The Y axis going from bottom to top, and the Z axis going from towards
     the screen to away from the screen. This can be made right-handed by making
     the near value greater than the far value.
+
+    Args:
+        left: Left limit of the projection
+        right: Right limit of the projection
+        bottom: Bottom limit of the projection
+        top: Top limit of the projection
+        near: Near plane
+        far: Far plane
     """
 
     __slots__ = ("rect", "near", "far")
 
     def __init__(
         self, left: float, right: float, bottom: float, top: float, near: float, far: float
     ):
-
-        # Data for generating Orthographic Projection matrix
         self.rect: Rect = LRBT(left, right, bottom, top)
-        #: The 'closest' visible position along the forward direction.
-        #:
-        #: It will get mapped to z = -1.0. Anything closer than this value
-        #: is not visible.
+        """Rectangle defining the projection area."""
+
         self.near: float = near
-        #: The 'farthest' visible position along the forward direction.
-        #:
-        #: It will get mapped to z = 1.0. Anything father than this value
-        #: is not visible.
+        """
+        The 'closest' visible position along the forward direction.
+
+        It will get mapped to z = -1.0. Anything closer than this value
+        is not visible.
+        """
+
         self.far: float = far
+        """
+        The 'farthest' visible position along the forward direction.
+
+        It will get mapped to z = 1.0. Anything father than this value
+        is not visible.
+        """
 
     @property
     def left(self) -> float:
-        """ "The left-side cutoff value, which gets mapped to x = -1.0.
+        """
+        The left-side cutoff value, which gets mapped to x = -1.0.
 
         Anything to the left of this value is not visible.
         """
@@ -148,7 +182,8 @@ def left(self, new_left: AsFloat):
 
     @property
     def right(self) -> float:
-        """ "The right-side cutoff value, which gets mapped to x = 1.0.
+        """
+        The right-side cutoff value, which gets mapped to x = 1.0.
 
         Anything to the left of this value is not visible.
         """
@@ -164,7 +199,8 @@ def right(self, new_right: AsFloat):
 
     @property
     def bottom(self) -> float:
-        """ "The bottom-side cutoff value, which gets mapped to -y = 1.0.
+        """
+        The bottom-side cutoff value, which gets mapped to -y = 1.0.
 
         Anything to the left of this value is not visible.
         """
@@ -180,7 +216,8 @@ def bottom(self, new_bottom: AsFloat):
 
     @property
     def top(self) -> float:
-        """ "The top-side cutoff value, which gets mapped to y = 1.0.
+        """
+        The top-side cutoff value, which gets mapped to y = 1.0.
 
         Anything to the left of this value is not visible.
         """
@@ -196,6 +233,7 @@ def top(self, new_top: AsFloat):
 
     @property
     def lrbt(self) -> tuple[float, float, float, float]:
+        """The left, right, bottom, and top values of the projection."""
         return self.rect.lrbt
 
     @lrbt.setter
@@ -212,39 +250,62 @@ def __repr__(self):
 
 
 def orthographic_from_rect(rect: Rect, near: float, far: float) -> OrthographicProjectionData:
+    """
+    Create an orthographic projection from a rectangle.
+
+    Args:
+        rect: The rectangle to create the projection from.
+        near: The near plane of the projection.
+        far: The far plane of the projection.
+    """
     return OrthographicProjectionData(rect.left, rect.right, rect.bottom, rect.top, near, far)
 
 
 class PerspectiveProjectionData:
-    """Describes a perspective projection.
-    )
+    """
+    Data for perspective projection.
+
+    Args:
+        aspect: The aspect ratio of the screen (width over height).
+        fov: The field of view in degrees.
+        near: The 'closest' visible position along the forward direction.
+        far: The 'farthest' visible position along the forward
     """
 
     __slots__ = ("aspect", "fov", "near", "far")
 
     def __init__(self, aspect: float, fov: float, near: float, far: float):
-        #: The aspect ratio of the screen (width over height).
         self.aspect: float = aspect
-        #: The field of view in degrees.
-        #:
-        #: Together with the aspect ratio, it defines the size of the
-        #: perspective projection for any given depth.
+        """The aspect ratio of the screen (width over height)."""
+
         self.fov: float = fov
-        #: The 'closest' visible position along the forward direction.
-        #:
-        #: It will get mapped to z = -1.0. Anything closer than this value
-        #: is not visible.
+        """
+        The field of view in degrees.
+
+        Together with the aspect ratio, it defines the size of the
+        perspective projection for any given depth.
+        """
+
         self.near: float = near
-        #: The 'farthest' visible position along the forward direction.
-        #:
-        #: It will get mapped to z = 1.0. Anything father than this value
-        #: is not visible.
+        """
+        The 'closest' visible position along the forward direction.
+
+        It will get mapped to z = -1.0. Anything closer than this value
+        is not visible.
+        """
+
         self.far: float = far
+        """"
+        The 'farthest' visible position along the forward direction.
 
-    def __str__(self):
+        It will get mapped to z = 1.0. Anything father than this value
+        is not visible.
+        """
+
+    def __str__(self) -> str:
         return f"PerspectiveProjection<{self.aspect=}, {self.fov=}, {self.near=}, {self.far=}>"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return self.__str__()
 
 

arcade/camera/static.py

@@ -105,6 +105,15 @@ def static_from_orthographic(
     *,
     window: Window | None = None,
 ) -> _StaticCamera:
+    """
+    Create a static camera from a CameraData and OrthographicProjectionData
+
+    Args:
+        view: The view matrix to use
+        orthographic: The orthographic projection to use
+        viewport: The viewport to use
+        window: The window to use
+    """
     return _StaticCamera(
         generate_view_matrix(view),
         generate_orthographic_matrix(orthographic, view.zoom),
@@ -122,6 +131,15 @@ def static_from_perspective(
     *,
     window: Window | None = None,
 ) -> _StaticCamera:
+    """
+    Create a static camera from a CameraData and PerspectiveProjectionData
+
+    Args:
+        view: The view matrix to use
+        perspective: The perspective projection to use
+        viewport: The viewport to use
+        window: The window
+    """
     return _StaticCamera(
         generate_view_matrix(view),
         generate_orthographic_matrix(perspective, view.zoom),
@@ -144,6 +162,20 @@ def static_from_raw_orthographic(
     *,
     window: Window | None = None,
 ) -> _StaticCamera:
+    """
+    Create a static camera from raw orthographic data.
+
+    Args:
+        projection: The orthographic projection to use
+        near: The near plane
+        far: The far plane
+        zoom: The zoom level
+        position: The position of the camera
+        up: The up vector
+        forward: The forward vector
+        viewport: The viewport
+        window: The window
+    """
     view = generate_view_matrix(CameraData(position, up, forward, zoom))
     proj = generate_orthographic_matrix(
         OrthographicProjectionData(
@@ -174,6 +206,21 @@ def static_from_raw_perspective(
     *,
     window: Window | None = None,
 ) -> _StaticCamera:
+    """
+    Create a static camera from raw perspective data.
+
+    Args:
+        aspect: The aspect ratio
+        fov: The field of view
+        near: The near plane
+        far: The far plane
+        zoom: The zoom level
+        position: The position of the camera
+        up: The up vector
+        forward: The forward vector
+        viewport: The viewport
+        window: The window
+    """
     view = generate_view_matrix(CameraData(position, up, forward, zoom))
     proj = generate_perspective_matrix(PerspectiveProjectionData(aspect, fov, near, far), zoom)
 
@@ -196,6 +243,17 @@ def static_from_matrices(
     project_method: Callable[[Point, tuple[int, int, int, int], Mat4, Mat4], Vec2] | None = None,
     unproject_method: Callable[[Point, tuple[int, int, int, int], Mat4, Mat4], Vec3] | None = None,
 ) -> _StaticCamera:
+    """
+    Create a static camera from raw matrices.
+
+    Args:
+        view: The view matrix
+        projection: The projection matrix
+        viewport: The viewport
+        window: The window
+        project_method: The project method
+        unproject_method: The unproject method
+    """
     return _StaticCamera(
         view,
         projection,

arcade/sprite/base.py

@@ -73,6 +73,7 @@ def __init__(
         self._visible = bool(visible)
         self._color: Color = WHITE
         self.sprite_lists: list["SpriteList"] = []
+        """The sprite lists this sprite is a member of"""
 
         # Core properties we don't use, but spritelist expects it
         self._angle = 0.0
@@ -403,6 +404,7 @@ def top(self, amount: float):
 
     @property
     def rect(self) -> Rect:
+        """A rectangle with with the sprites left, right, bottom, and top values."""
         return LRBT(self.left, self.right, self.bottom, self.top)
 
     @property
@@ -722,6 +724,7 @@ def rescale_xy_relative_to_point(self, point: Point, factors_xy: Iterable[float]
 
     @property
     def hit_box(self) -> HitBox:
+        """The hit box for this sprite."""
         return self._hit_box
 
     def update_spatial_hash(self) -> None:

arcade/sprite/mixins.py

@@ -14,16 +14,32 @@ class PyMunk:
 
     def __init__(self):
         self.damping: float | None = None
+        """
+        Natural damping.
+
+        Damping is applied to objects to simulate the natural deceleration of
+        objects due to friction.
+        """
+
         self.gravity: tuple[float, float] | None = None
+        """Gravity applied to the object."""
+
         self.max_velocity: float | None = None
+        """Maximum velocity allowed."""
+
         self.max_horizontal_velocity: float | None = None
+        """Maximum horizontal velocity allowed."""
+
         self.max_vertical_velocity: float | None = None
+        """Maximum vertical velocity allowed."""
 
 
 class PymunkMixin:
+    """A mixin class that adds Pymunk physics to a sprite."""
 
     def __init__(self) -> None:
         self.pymunk = PyMunk()
+        """Object used to hold pymunk info for a sprite."""
         self.force = [0.0, 0.0]
         """force vector used by pymunk"""