Fix docstrings and comments

sfe-SparkFro · sfe-SparkFro · commit f5f4f0aea2ac · 2025-12-12T17:01:13.000-07:00
diff --git a/red_vision/cameras/dvp_camera.py b/red_vision/cameras/dvp_camera.py
@@ -29,19 +29,26 @@ def __init__(
         Args:
             i2c (I2C): I2C object for communication
             i2c_address (int): I2C address of the camera
+            height (int, optional): Image height in pixels
+            width (int, optional): Image width in pixels
+            color_mode (int, optional): Color mode to use
+            buffer (ndarray, optional): Pre-allocated image buffer
         """
-        super().__init__(height, width, color_mode, buffer)
-
+        # Store I2C parameters.
         self._i2c = i2c
         self._i2c_address = i2c_address
 
+        # Initialize the base VideoCaptureDriver class
+        super().__init__(height, width, color_mode, buffer)
+
     def _read_register(self, reg, nbytes=1):
         """
-        Reads a register from the camera over I2C.
+        Reads a register(s) from the camera over I2C.
 
         Args:
-            reg (int): Register address to read
-            nbytes (int): Number of bytes to read from the register
+            reg (int): Start register address to read
+            nbytes (int, optional): Number of bytes to read from the register
+                (default: 1)
 
         Returns:
             bytes: Data read from the register
@@ -51,11 +58,11 @@ def _read_register(self, reg, nbytes=1):
 
     def _write_register(self, reg, data):
         """
-        Writes data to a register on the camera over I2C.
+        Writes data to a register(s) on the camera over I2C.
 
         Args:
-            reg (int): Register address to write
-            data (bytes, int, list, tuple): Data to write to the register
+            reg (int): Start register address to write
+            data (bytes, int, list, tuple): Data to write to the register(s)
         """
         if isinstance(data, int):
             data = bytes([data])
diff --git a/red_vision/cameras/dvp_rp2_pio.py b/red_vision/cameras/dvp_rp2_pio.py
@@ -38,25 +38,22 @@ def __init__(
         Initializes the DVP interface with the specified parameters.
 
         Args:
+            sm_id (int): PIO state machine ID
             pin_d0 (int): Data 0 pin number for DVP interface
             pin_vsync (int): Vertical sync pin number
             pin_hsync (int): Horizontal sync pin number
             pin_pclk (int): Pixel clock pin number
-            pin_xclk (int): External clock pin number
-            xclk_freq (int): Frequency in Hz for the external clock
-            sm_id (int): PIO state machine ID
-            num_data_pins (int): Number of data pins used in DVP interface
-            bytes_per_pixel (int): Number of bytes per pixel
-            byte_swap (bool): Whether to swap bytes in the captured data
-            continuous (bool): Whether to continuously capture frames
+            pin_xclk (int, optional): External clock pin number
         """
+        # Store state machine ID
+        self._sm_id = sm_id
+
         # Store pin assignments
         self._pin_d0 = pin_d0
         self._pin_vsync = pin_vsync
         self._pin_hsync = pin_hsync
         self._pin_pclk = pin_pclk
         self._pin_xclk = pin_xclk
-        self._sm_id = sm_id
 
     def begin(
             self,
@@ -66,6 +63,18 @@ def begin(
             byte_swap,
             continuous = False,
         ):
+        """
+        Begins the DVP interface with the specified parameters.
+
+        Args:
+            buffer (ndarray): Image buffer to write captured frames into
+            xclk_freq (int): Frequency in Hz for the XCLK pin, if it is used
+            num_data_pins (int): Number of data pins used by the camera (1 to 8)
+            byte_swap (bool): Whether to swap bytes in each pixel
+            continuous (bool, optional): Whether to continuously capture frames
+                (default: False)
+        """
+        # Store buffer and its dimensions
         self._buffer = buffer
         self._height, self._width, self._bytes_per_pixel = buffer.shape
 
@@ -108,14 +117,17 @@ def begin(
 
     def buffer(self):
         """
-        Returns the current frame buffer from the camera.
+        Returns the current frame buffer used by this driver.
 
         Returns:
             ndarray: Frame buffer
         """
         return self._buffer
 
     def _setup_pio(self):
+        """
+        Sets up the PIO state machine for the DVP interface.
+        """
         # Copy the PIO program
         program = self._pio_read_dvp
 
@@ -505,6 +517,9 @@ def _assemble_control_blocks(self):
     def _add_control_block(self, block):
         """
         Helper function to add a control block to the control block array.
+
+        Args:
+            block (array): Control block to add
         """
         # Add the control block to the array. Each control block is all 4 DMA
         # alias 0 registers in order.
diff --git a/red_vision/cameras/hm01b0.py b/red_vision/cameras/hm01b0.py
@@ -249,18 +249,33 @@ def __init__(
         Initializes the HM01B0 camera with default settings.
 
         Args:
+            interface (DVP_Interface): DVP interface driver
             i2c (I2C): I2C object for communication
-            i2c_address (int, optional): I2C address (default: 0x24)
-            num_data_pins (int, optional): Number of data pins
-                - 1 (Default)
+            i2c_address (int, optional): I2C address of the camera (default: 0x24)
+            num_data_pins (int, optional): Number of data pins for the camera to
+                use:
+                - 1 (default)
                 - 4
                 - 8
+            xclk_freq (int, optional): Frequency of the XCLK signal in Hz
+                (default: 25MHz)
+            continuous (bool, optional): Whether to run in continuous capture
+                mode (default: False)
+            height (int, optional): Image height in pixels
+            width (int, optional): Image width in pixels
+            color_mode (int, optional): Color mode to use:
+                - COLOR_MODE_BAYER_RG (default)
+            buffer (ndarray, optional): Pre-allocated image buffer
         """
+        # Store parameters
         self._interface = interface
         self._continuous = continuous
         self._num_data_pins = num_data_pins
+
+        # Initialize the base DVP_Camera class
         super().__init__(i2c, i2c_address, height, width, color_mode, buffer)
 
+        # Begin the interface driver
         self._interface.begin(
             self._buffer,
             xclk_freq = xclk_freq,
@@ -269,6 +284,7 @@ def __init__(
             continuous = self._continuous,
         )
 
+        # Reset and initialize the camera
         self._soft_reset()
         self._send_init(self._num_data_pins)
 
diff --git a/red_vision/cameras/ov5640.py b/red_vision/cameras/ov5640.py
@@ -891,6 +891,7 @@ def __init__(
         interface,
         i2c,
         i2c_address = 0x3C,
+        xclk_freq = 20_000_000,
         continuous = False,
         height = None,
         width = None,
@@ -901,23 +902,39 @@ def __init__(
         Initializes the OV5640 camera sensor with default settings.
 
         Args:
+            interface (DVP_Interface): DVP interface driver
             i2c (I2C): I2C object for communication
-            i2c_address (int, optional): I2C address (default: 0x3C)
+            i2c_address (int, optional): I2C address of the camera (default: 0x3C)
+            xclk_freq (int, optional): Frequency of the XCLK signal in Hz
+                (default: 20MHz)
+            continuous (bool, optional): Whether to run in continuous capture
+                mode (default: False)
+            height (int, optional): Image height in pixels
+            width (int, optional): Image width in pixels
+            color_mode (int, optional): Color mode to use:
+                - COLOR_MODE_BGR565 (default)
+            buffer (ndarray, optional): Pre-allocated image buffer
         """
+        # Store parameters
         self._interface = interface
         self._continuous = continuous
+
+        # Initialize the base DVP_Camera class
         super().__init__(i2c, i2c_address, height, width, color_mode, buffer)
 
+        # Begin the interface driver
         self._interface.begin(
             self._buffer,
-            xclk_freq = 20_000_000,
+            xclk_freq = xclk_freq,
             num_data_pins = 8,
             byte_swap = False,
             continuous = self._continuous,
         )
 
+        # Initialize the camera
         self._write_list(self._sensor_default_regs)
 
+        # Set default settings
         self._colorspace = self._OV5640_COLOR_RGB
         self._flip_x = True
         self._flip_y = True
@@ -930,6 +947,7 @@ def __init__(
         self._ev = 0
         self._white_balance = 0
 
+        # Apply the initial size and colorspace
         self._set_size_and_colorspace()
 
     def resolution_default(self):
diff --git a/red_vision/cameras/video_capture.py b/red_vision/cameras/video_capture.py
@@ -22,7 +22,10 @@ def __init__(
             driver,
             ):
         """
-        Initializes the camera.
+        Initializes a VideoCapture object with the provided driver.
+
+        Args:
+            driver (VideoCaptureDriver): Camera driver to use
         """
         # Store driver reference.
         self._driver = driver
diff --git a/red_vision/cameras/video_capture_driver.py b/red_vision/cameras/video_capture_driver.py
@@ -14,6 +14,8 @@ class VideoCaptureDriver(VideoDriver):
     """
     Red Vision abstract base class for camera drivers.
     """
+    # No __init__() here, see VideoDriver.
+
     def open(self):
         """
         Opens the camera and prepares it for capturing images.
diff --git a/red_vision/displays/dvi.py b/red_vision/displays/dvi.py
@@ -28,20 +28,20 @@ def __init__(
         Args:
             width (int): Display width in pixels
             height (int): Display height in pixels
-            rotation (int, optional): Orientation of display
-              - 0: Portrait (default)
-              - 1: Landscape
-              - 2: Inverted portrait
-              - 3: Inverted landscape
-            bgr_order (bool, optional): Color order
-              - True: BGR (default)
-              - False: RGB
-            reverse_bytes_in_word (bool, optional):
-              - Enable if the display uses LSB byte order for color words
+            color_mode (int, optional): Color mode
+              - COLOR_BGR233
+              - COLOR_GRAY8
+              - COLOR_BGR565 (default)
+              - COLOR_BGRA8888
+            buffer (ndarray, optional): Pre-allocated frame buffer.
         """
+        # Store parameters
         self._interface = interface
+
+        # Initialize the base display class
         super().__init__(height, width, color_mode, buffer)
 
+        # Begin the interface driver
         self._interface.begin(
             self._buffer,
             self._color_mode,
diff --git a/red_vision/displays/dvi_rp2_hstx.py b/red_vision/displays/dvi_rp2_hstx.py
@@ -120,13 +120,6 @@ def __init__(
         Initializes the DVI HSTX display driver.
 
         Args:
-            width (int): Display width in pixels
-            height (int): Display height in pixels
-            color_mode (int, optional): Color mode
-              - COLOR_BGR233: 8-bit BGR233
-              - COLOR_GRAY8: 8-bit grayscale
-              - COLOR_BGR565: 16-bit BGR565 (default)
-              - COLOR_BGRA8888: 32-bit BGRA8888
             pin_clk_p (int, optional): TMDS clock lane positive pin (default: 14)
             pin_clk_n (int, optional): TMDS clock lane negative pin (default: 15)
             pin_d0_p (int, optional): TMDS data 0 lane positive pin (default: 18)
@@ -135,7 +128,6 @@ def __init__(
             pin_d1_n (int, optional): TMDS data 1 lane negative pin (default: 17)
             pin_d2_p (int, optional): TMDS data 2 lane positive pin (default: 12)
             pin_d2_n (int, optional): TMDS data 2 lane negative pin (default: 13)
-            buffer (ndarray, optional): Pre-allocated frame buffer.
         """
         # Set pin numbers.
         self._pin_clk_p = pin_clk_p
@@ -150,6 +142,10 @@ def __init__(
     def begin(self, buffer, color_mode):
         """
         Begins DVI output.
+
+        Args:
+            buffer (ndarray): Image buffer to read pixel data from
+            color_mode (int): Color mode of the image buffer
         """
         # Store buffer and color mode.
         self._buffer = buffer
diff --git a/red_vision/displays/spi_generic.py b/red_vision/displays/spi_generic.py
@@ -33,21 +33,9 @@ def __init__(
         Initializes the ST7789 SPI display driver.
 
         Args:
-            width (int): Display width in pixels
-            height (int): Display height in pixels
-            spi (SPI): SPI bus object
+            spi (SPI): SPI interface object
             pin_dc (int): Data/Command pin number
             pin_cs (int, optional): Chip Select pin number
-            rotation (int, optional): Orientation of display
-              - 0: Portrait (default)
-              - 1: Landscape
-              - 2: Inverted portrait
-              - 3: Inverted landscape
-            bgr_order (bool, optional): Color order
-              - True: BGR (default)
-              - False: RGB
-            reverse_bytes_in_word (bool, optional):
-              - Enable if the display uses LSB byte order for color words
         """
         # Store SPI arguments
         self._spi = spi
diff --git a/red_vision/displays/spi_rp2_pio.py b/red_vision/displays/spi_rp2_pio.py
@@ -39,25 +39,13 @@ def __init__(
         Initializes the ST7789 PIO display driver.
 
         Args:
-            width (int): Display width in pixels
-            height (int): Display height in pixels
             sm_id (int): PIO state machine ID
             pin_clk (int): Clock pin number
             pin_tx (int): Data pin number
             pin_dc (int): Data/Command pin number
             pin_cs (int, optional): Chip Select pin number
-            freq (int, optional): Frequency in Hz for the PIO state machine
-                Default is -1, which uses the default frequency of 125MHz
-            rotation (int, optional): Orientation of display
-              - 0: Portrait (default)
-              - 1: Landscape
-              - 2: Inverted portrait
-              - 3: Inverted landscape
-            bgr_order (bool, optional): Color order
-              - True: BGR (default)
-              - False: RGB
-            reverse_bytes_in_word (bool, optional):
-              - Enable if the display uses LSB byte order for color words
+            freq (int, optional): Frequency in Hz for the PIO state machine.
+                Default is -1, which uses the system clock frequency
         """
         # Store PIO arguments
         self._sm_id = sm_id
diff --git a/red_vision/displays/st7789.py b/red_vision/displays/st7789.py
diff --git a/red_vision/displays/video_display.py b/red_vision/displays/video_display.py
diff --git a/red_vision/displays/video_display_driver.py b/red_vision/displays/video_display_driver.py
diff --git a/red_vision/utils/video_driver.py b/red_vision/utils/video_driver.py
