Resolve missing docstrings and minor lint issues

Author: HexDecimal

tcod/map.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import warnings
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any, Final, Literal
 
 import numpy as np
 from typing_extensions import deprecated
@@ -31,13 +31,6 @@ class Map:
         height (int): Height of the new Map.
         order (str): Which numpy memory order to use.
 
-    Attributes:
-        width (int): Read only width of this Map.
-        height (int): Read only height of this Map.
-        transparent: A boolean array of transparent cells.
-        walkable: A boolean array of walkable cells.
-        fov: A boolean array of the cells lit by :any:'compute_fov'.
-
     Example::
 
         >>> import tcod
@@ -80,8 +73,10 @@ def __init__(
         order: Literal["C", "F"] = "C",
     ) -> None:
         """Initialize the map."""
-        self.width = width
-        self.height = height
+        self.width: Final = width
+        """Read only width of this Map."""
+        self.height: Final = height
+        """Read only height of this Map."""
         self._order: Literal["C", "F"] = tcod._internal.verify_order(order)
 
         self._buffer: NDArray[np.bool_] = np.zeros((height, width, 3), dtype=np.bool_)
@@ -100,16 +95,19 @@ def __as_cdata(self) -> Any:  # noqa: ANN401
 
     @property
     def transparent(self) -> NDArray[np.bool_]:
+        """A boolean array of transparent cells."""
         buffer: np.ndarray[Any, np.dtype[np.bool_]] = self._buffer[:, :, 0]
         return buffer.T if self._order == "F" else buffer
 
     @property
     def walkable(self) -> NDArray[np.bool_]:
+        """A boolean array of walkable cells."""
         buffer: np.ndarray[Any, np.dtype[np.bool_]] = self._buffer[:, :, 1]
         return buffer.T if self._order == "F" else buffer
 
     @property
     def fov(self) -> NDArray[np.bool_]:
+        """A boolean array of the cells lit by :any:'compute_fov'."""
         buffer: np.ndarray[Any, np.dtype[np.bool_]] = self._buffer[:, :, 2]
         return buffer.T if self._order == "F" else buffer
 
@@ -146,6 +144,7 @@ def compute_fov(
         lib.TCOD_map_compute_fov(self.map_c, x, y, radius, light_walls, algorithm)
 
     def __setstate__(self, state: dict[str, Any]) -> None:
+        """Unpickle this instance."""
         if "_Map__buffer" in state:  # Deprecated since 19.6
             state["_buffer"] = state.pop("_Map__buffer")
         if "buffer" in state:  # Deprecated
@@ -159,6 +158,7 @@ def __setstate__(self, state: dict[str, Any]) -> None:
         self.map_c = self.__as_cdata()
 
     def __getstate__(self) -> dict[str, Any]:
+        """Pickle this instance."""
         state = self.__dict__.copy()
         del state["map_c"]
         return state

tcod/noise.py

@@ -66,6 +66,7 @@ class Algorithm(enum.IntEnum):
     """Wavelet noise."""
 
     def __repr__(self) -> str:
+        """Return the string representation for this algorithm."""
         return f"tcod.noise.Algorithm.{self.name}"
 
 
@@ -88,6 +89,7 @@ class Implementation(enum.IntEnum):
     """Turbulence noise implementation."""
 
     def __repr__(self) -> str:
+        """Return the string representation for this implementation."""
         return f"tcod.noise.Implementation.{self.name}"
 
 
@@ -161,27 +163,30 @@ def __rng_from_seed(seed: None | int | tcod.random.Random) -> tcod.random.Random
         return seed
 
     def __repr__(self) -> str:
+        """Return the string representation of this noise instance."""
         parameters = [
             f"dimensions={self.dimensions}",
             f"algorithm={self.algorithm!r}",
             f"implementation={Implementation(self.implementation)!r}",
         ]
-        if self.hurst != 0.5:
+        if self.hurst != 0.5:  # noqa: PLR2004 # Default value
             parameters.append(f"hurst={self.hurst}")
-        if self.lacunarity != 2:
+        if self.lacunarity != 2:  # noqa: PLR2004 # Default value
             parameters.append(f"lacunarity={self.lacunarity}")
-        if self.octaves != 4:
+        if self.octaves != 4:  # noqa: PLR2004 # Default value
             parameters.append(f"octaves={self.octaves}")
         if self._seed is not None:
             parameters.append(f"seed={self._seed}")
         return f"tcod.noise.Noise({', '.join(parameters)})"
 
     @property
     def dimensions(self) -> int:
+        """Number of dimensions supported by this noise generator."""
         return int(self._tdl_noise_c.dimensions)
 
     @property
     def algorithm(self) -> int:
+        """Current selected algorithm. Can be changed."""
         noise_type = self.noise_c.noise_type
         return Algorithm(noise_type) if noise_type else Algorithm.SIMPLEX
 
@@ -191,6 +196,7 @@ def algorithm(self, value: int) -> None:
 
     @property
     def implementation(self) -> int:
+        """Current selected implementation. Can be changed."""
         return Implementation(self._tdl_noise_c.implementation)
 
     @implementation.setter
@@ -202,14 +208,17 @@ def implementation(self, value: int) -> None:
 
     @property
     def hurst(self) -> float:
+        """Noise hurst exponent. Can be changed."""
         return float(self.noise_c.H)
 
     @property
     def lacunarity(self) -> float:
+        """Noise lacunarity. Can be changed."""
         return float(self.noise_c.lacunarity)
 
     @property
     def octaves(self) -> float:
+        """Level of detail on fBm and turbulence implementations. Can be changed."""
         return float(self._tdl_noise_c.octaves)
 
     @octaves.setter
@@ -343,6 +352,7 @@ def sample_ogrid(self, ogrid: Sequence[ArrayLike]) -> NDArray[np.float32]:
         return out
 
     def __getstate__(self) -> dict[str, Any]:
+        """Support picking this instance."""
         state = self.__dict__.copy()
         if self.dimensions < 4 and self.noise_c.waveletTileData == ffi.NULL:  # noqa: PLR2004
             # Trigger a side effect of wavelet, so that copies will be synced.
@@ -374,6 +384,7 @@ def __getstate__(self) -> dict[str, Any]:
         return state
 
     def __setstate__(self, state: dict[str, Any]) -> None:
+        """Unpickle this instance."""
         if isinstance(state, tuple):  # deprecated format
             return self._setstate_old(state)
         # unpack wavelet tile data if it exists

tcod/path.py

@@ -112,6 +112,7 @@ def __init__(
         callback: Callable[[int, int, int, int], float],
         shape: tuple[int, int],
     ) -> None:
+        """Initialize this callback."""
         self.callback = callback
         super().__init__(callback, shape)
 
@@ -139,6 +140,7 @@ def __new__(cls, array: ArrayLike) -> Self:
         return np.asarray(array).view(cls)
 
     def __repr__(self) -> str:
+        """Return the string representation of this object."""
         return f"{self.__class__.__name__}({repr(self.view(np.ndarray))!r})"
 
     def get_tcod_path_ffi(self) -> tuple[Any, Any, tuple[int, int]]:
@@ -1068,10 +1070,12 @@ def __init__(self, *, cost: ArrayLike, cardinal: int, diagonal: int, greed: int
 
     @property
     def ndim(self) -> int:
+        """Number of dimensions."""
         return 2
 
     @property
     def shape(self) -> tuple[int, int]:
+        """Shape of this graph."""
         return self._shape
 
     @property

tcod/sdl/joystick.py

@@ -103,6 +103,7 @@ class Joystick:
     """Currently opened joysticks."""
 
     def __init__(self, sdl_joystick_p: Any) -> None:  # noqa: ANN401
+        """Wrap an SDL joystick C pointer."""
         self.sdl_joystick_p: Final = sdl_joystick_p
         """The CFFI pointer to an SDL_Joystick struct."""
         self.axes: Final[int] = _check_int(lib.SDL_GetNumJoystickAxes(self.sdl_joystick_p), failure=-1)
@@ -135,11 +136,13 @@ def _from_instance_id(cls, instance_id: int) -> Joystick:
         return cls._by_instance_id[instance_id]
 
     def __eq__(self, other: object) -> bool:
+        """Return True if `self` and `other` refer to the same joystick."""
         if isinstance(other, Joystick):
             return self.id == other.id
         return NotImplemented
 
     def __hash__(self) -> int:
+        """Return the joystick id as a hash."""
         return hash(self.id)
 
     def _get_guid(self) -> str:
@@ -173,6 +176,7 @@ class GameController:
     """Currently opened controllers."""
 
     def __init__(self, sdl_controller_p: Any) -> None:  # noqa: ANN401
+        """Wrap an SDL controller C pointer."""
         self.sdl_controller_p: Final = sdl_controller_p
         self.joystick: Final = Joystick(lib.SDL_GetGamepadJoystick(self.sdl_controller_p))
         """The :any:`Joystick` associated with this controller."""
@@ -200,11 +204,13 @@ def get_axis(self, axis: ControllerAxis) -> int:
         return int(lib.SDL_GetGamepadAxis(self.sdl_controller_p, axis))
 
     def __eq__(self, other: object) -> bool:
+        """Return True if `self` and `other` are both controllers referring to the same joystick."""
         if isinstance(other, GameController):
             return self.joystick.id == other.joystick.id
         return NotImplemented
 
     def __hash__(self) -> int:
+        """Return the joystick id as a hash."""
         return hash(self.joystick.id)
 
     # These could exist as convenience functions, but the get_X functions are probably better.

tcod/sdl/mouse.py

@@ -28,6 +28,7 @@ class Cursor:
     """A cursor icon for use with :any:`set_cursor`."""
 
     def __init__(self, sdl_cursor_p: Any) -> None:  # noqa: ANN401
+        """Wrap an SDL cursor C pointer."""
         if ffi.typeof(sdl_cursor_p) is not ffi.typeof("struct SDL_Cursor*"):
             msg = f"Expected a {ffi.typeof('struct SDL_Cursor*')} type (was {ffi.typeof(sdl_cursor_p)})."
             raise TypeError(msg)
@@ -37,9 +38,13 @@ def __init__(self, sdl_cursor_p: Any) -> None:  # noqa: ANN401
         self.p = sdl_cursor_p
 
     def __eq__(self, other: object) -> bool:
-        return bool(self.p == getattr(other, "p", None))
+        """Return True if `self` is the same cursor as `other`."""
+        if isinstance(other, Cursor):
+            return bool(self.p == getattr(other, "p", None))
+        return NotImplemented
 
     def __hash__(self) -> int:
+        """Returns the hash of this objects C pointer."""
         return hash(self.p)
 
     @classmethod