Refactor docstrings to include class references for better clarity

Author: Natuworkguy

engine/core/__init__.py

@@ -339,7 +339,8 @@ def __init__(self, *, parent: "Game") -> None:
 
     def _get_colliding_entities(self, entity: Entity) -> list[Entity]:
         """
-        Internal collision query used by Entity.get_colliding_entities().
+        Internal collision query used by
+        :meth:`~engine.core.Entity.get_colliding_entities`.
 
         Args:
             entity (Entity): Entity to evaluate collisions for.

engine/core/animation.py

@@ -13,10 +13,11 @@
 
 class EntityAnim:
     """
-    Manage an animation for an entity.
+    Manage an animation for an :class:`~engine.core.Entity`.
 
-    Stands in for EntityImage when an entity should show a moving image (GIF
-    or WebP) instead of a still one. It offers the same three methods, so an
+    Stands in for :class:`~engine.core.image.EntityImage`
+    when an entity should show a moving image (GIF or WebP)
+    instead of a still one. It offers the same three methods, so an
     entity holding one needs no special handling, and frames advance off the
     clock on their own: drawing it is all the caller has to do. The animation
     loops for as long as it keeps being drawn, at the pace the file asks for.

engine/core/image.py

@@ -12,14 +12,15 @@
 
 class EntityImage:
     """
-    Manage a pygame image surface for an entity.
+    Manage a pygame image surface for an :class:`~engine.core.Entity`.
     """
 
     surface: Optional[pygame.Surface]
 
     def __init__(self, image_path: str) -> None:
         """
-        Initialize the EntityImage by loading the image at ``image_path``.
+        Initialize the :class:`~engine.core.image.EntityImage` by loading the
+        image at ``image_path``.
 
         Args:
             image_path (str): The path to the image file.

engine/core/ose.py

@@ -13,19 +13,19 @@
 
 def _script_defines(scriptobj: EntityScriptType, name: str) -> bool:
     """
-    Check whether scriptobj itself defines `name`, rather than inheriting
-    it from Entity. Since script classes are commonly subclasses of Entity
-    (for typing convenience), a plain hasattr() check would also match
-    Entity's own init/update/event, causing infinite recursion when they
-    are dispatched.
+    Check whether scriptobj itself defines ``name``, rather than inheriting
+    it from :class:`~engine.core.Entity`. Since script classes are commonly
+    subclasses of :class:`~engine.core.Entity` (for typing convenience), a
+    plain hasattr() check would also match its own init/update/event,
+    causing infinite recursion when they are dispatched.
 
 
     Args:
         scriptobj (EntityScriptType): The script object to check.
         name (str): The name of the method to check for.
 
     Returns:
-        bool: True if scriptobj defines `name`, False otherwise.
+        bool: True if scriptobj defines ``name``, False otherwise.
     """
 
     func: Optional[Callable] = getattr(scriptobj, name, None)
@@ -39,16 +39,20 @@ class ObjectScriptEntity(Entity):
 
     def __new__(cls, *args: Any, scriptobj: EntityScriptType, **kwargs: Any) -> Any:
         """
-        Create an Entity configured to dispatch lifecycle calls to ``scriptobj``.
+        Create an :class:`~engine.core.Entity` configured to dispatch lifecycle
+        calls to ``scriptobj``.
 
         Args:
-            *args (Any): Positional arguments forwarded to Entity.
+            *args (Any): Positional arguments forwarded to
+                Entity.
             scriptobj (EntityScriptType): Object script providing optional
                 init, update, and event methods.
-            **kwargs (Any): Keyword arguments forwarded to Entity.
+            **kwargs (Any): Keyword arguments forwarded to
+                Entity.
 
         Returns:
-            Any: Entity instance with object-script dispatch metadata attached.
+            Any: :class:`~engine.core.Entity` instance with object-script
+                dispatch metadata attached.
         """
 
         kwargs["scriptfile"] = None