chore: add documentation RI

Code functionality left unchanged, only added docs where missing

close: N25B-298

test/unit/test_microphone_utils.py

@@ -7,6 +7,16 @@ from robot_interface.utils.microphone import choose_mic_default, choose_mic_inte
 
 
 class MockPyAudio:
+    """
+    A mock implementation of the PyAudio library class, designed for testing
+    microphone utility functions without requiring actual audio hardware.
+
+    It provides fake devices, including one input microphone, and implements
+    the core PyAudio methods required for device enumeration.
+
+    :ivar devices: A list of dictionaries representing mock audio devices.
+    :type devices: List[Dict[str, Any]]
+    """
     def __init__(self):
         # You can predefine fake device info here
         self.devices = [
@@ -37,18 +47,36 @@ class MockPyAudio:
         ]
 
     def get_device_count(self):
-        """Return the number of available mock devices."""
+        """
+        Returns the number of available mock devices.
+
+        :return: The total number of devices in the mock list.
+        :rtype: int
+        """
         return len(self.devices)
 
     def get_device_info_by_index(self, index):
-        """Return information for a given mock device index."""
+        """
+        Returns information for a given mock device index.
+
+        :param index: The index of the device to retrieve.
+        :type index: int
+
+        :return: A dictionary containing device information.
+        :rtype: Dict[str, Any]
+        """
         if 0 <= index < len(self.devices):
             return self.devices[index]
         else:
             raise IOError("Invalid device index: {}".format(index))
 
     def get_default_input_device_info(self):
-        """Return info for a default mock input device."""
+        """
+        Returns information for the default mock input device.
+
+        :return: A dictionary containing the default input device information.
+        :rtype: Dict[str, Any]
+        """
         for device in self.devices:
             if device.get("maxInputChannels", 0) > 0:
                 return device
@@ -57,16 +85,32 @@ class MockPyAudio:
 
 @pytest.fixture
 def pyaudio_instance():
+    """
+    A pytest fixture that returns an instance of the `MockPyAudio` class.
+
+    :return: An initialized instance of the mock PyAudio class.
+    :rtype: MockPyAudio
+    """
     return MockPyAudio()
 
 
 def _raise_io_error():
+    """
+    Helper function used to mock PyAudio methods that are expected to fail 
+    when no device is available.
+    """
     raise IOError()
 
 
 class TestAudioUnit(MicrophoneUtils):
-    """Run shared audio behavior tests with the mock implementation."""
+    """
+    Runs the shared microphone behavior tests defined in `MicrophoneUtils` using
+    the mock PyAudio implementation.
+    """
     def test_choose_mic_default_no_mic(self):
+        """
+        Tests `choose_mic_default` when no microphones are available.
+        """
         mock_pyaudio = mock.Mock()
         mock_pyaudio.get_device_count = mock.Mock(return_value=0L)
         mock_pyaudio.get_default_input_device_info = _raise_io_error
@@ -76,6 +120,9 @@ class TestAudioUnit(MicrophoneUtils):
         assert result is None
 
     def test_choose_mic_interactive_no_mic(self):
+        """
+        Tests `choose_mic_interactive` when no microphones are available.
+        """
         mock_pyaudio = mock.Mock()
         mock_pyaudio.get_device_count = mock.Mock(return_value=0L)
         mock_pyaudio.get_default_input_device_info = _raise_io_error