Add additional documentation

Author: sebromero

src/modulino/buttons.py

@@ -3,13 +3,16 @@
 from micropython import const
 
 class ModulinoButtons(Modulino):
+  """
+  Class to interact with the buttons of the Modulino Buttons.
+  """
 
   default_addresses = [0x7C]
-  default_long_press_duration = const(1000) # 1 second
+  _default_long_press_duration = const(1000) # 1 second
 
   def __init__(self, i2c_bus=None, address=None):
     super().__init__(i2c_bus, address, "BUTTONS")
-    self.long_press_duration = self.default_long_press_duration
+    self.long_press_duration = self._default_long_press_duration
 
     self._current_buttons_status = [None, None, None]
     self._last_press_timestamps = [None, None, None]
@@ -25,7 +28,7 @@ def __init__(self, i2c_bus=None, address=None):
     self._on_button_b_long_press = None
     self._on_button_c_long_press = None
 
-  def set_led_status(self, a, b, c):
+  def set_led_status(self, a: bool, b: bool, c: bool):
     """
     Turn on or off the button LEDs according to the given status.
 
@@ -41,23 +44,23 @@ def set_led_status(self, a, b, c):
     self.write(data)
 
   @property
-  def long_press_duration(self):
-    """
+  def long_press_duration(self) -> int:
+    """    
     Returns the duration in milliseconds that the button must 
     be pressed to trigger the long press event
     """
     return self._long_press_duration
 
   @long_press_duration.setter
-  def long_press_duration(self, value):
+  def long_press_duration(self, value : int):
     """
     Sets the duration in milliseconds that the button must 
     be pressed to trigger the long press event
     """
     self._long_press_duration = value
 
   @property
-  def on_button_a_press(self):
+  def on_button_a_press(self) -> function:
     """
     Returns the callback for the press event of button A.    
     """
@@ -71,7 +74,7 @@ def on_button_a_press(self, value):
     self._on_button_a_press = value
 
   @property
-  def on_button_a_release(self):
+  def on_button_a_release(self) -> function:
     """
     Returns the callback for the release event of button A.
     """
@@ -85,7 +88,7 @@ def on_button_a_release(self, value):
     self._on_button_a_release = value
 
   @property
-  def on_button_a_long_press(self):
+  def on_button_a_long_press(self) -> function:
     """
     Returns the callback for the long press event of button A.
     """
@@ -99,7 +102,7 @@ def on_button_a_long_press(self, value):
     self._on_button_a_long_press = value
 
   @property
-  def on_button_b_press(self):
+  def on_button_b_press(self) -> function:
     """
     Returns the callback for the press event of button B.
     """
@@ -113,7 +116,7 @@ def on_button_b_press(self, value):
     self._on_button_b_press = value
 
   @property
-  def on_button_b_release(self):
+  def on_button_b_release(self) -> function:
     """
     Returns the callback for the release event of button B.
     """
@@ -127,7 +130,7 @@ def on_button_b_release(self, value):
     self._on_button_b_release = value
 
   @property
-  def on_button_b_long_press(self):
+  def on_button_b_long_press(self) -> function:
     """
     Returns the callback for the long press event of button B.
     """
@@ -141,7 +144,7 @@ def on_button_b_long_press(self, value):
     self._on_button_b_long_press = value
 
   @property
-  def on_button_c_press(self):
+  def on_button_c_press(self) -> function:
     """
     Returns the callback for the press event of button C.
     """
@@ -155,7 +158,7 @@ def on_button_c_press(self, value):
     self._on_button_c_press = value
 
   @property
-  def on_button_c_release(self):
+  def on_button_c_release(self) -> function:
     """
     Returns the callback for the release event of button C.
     """
@@ -169,7 +172,7 @@ def on_button_c_release(self, value):
     self._on_button_c_release = value
 
   @property
-  def on_button_c_long_press(self):
+  def on_button_c_long_press(self) -> function:
     """
     Returns the callback for the long press event of button C.
     """
@@ -182,7 +185,7 @@ def on_button_c_long_press(self, value):
     """
     self._on_button_c_long_press = value
 
-  def update(self):
+  def update(self) -> bool:
     """
     Update the button status and call the corresponding callbacks.
     Returns True if any of the buttons has changed its state.
@@ -240,7 +243,7 @@ def update(self):
 
     return button_states_changed
 
-  def is_pressed(self, index):
+  def is_pressed(self, index) -> bool:
     """
     Returns True if the button at the given index is currently pressed.
 
@@ -257,14 +260,14 @@ def button_a_pressed(self):
     return self.is_pressed(0)
 
   @property
-  def button_b_pressed(self):
+  def button_b_pressed(self) -> bool:
     """
     Returns True if button B is currently pressed.
     """
     return self.is_pressed(1)
 
   @property
-  def button_c_pressed(self):
+  def button_c_pressed(self) -> bool:
     """
     Returns True if button C is currently pressed.
     """

src/modulino/buzzer.py

@@ -3,21 +3,10 @@
 
 class ModulinoBuzzer(Modulino):
   """
-  Class to play tones on the buzzer of the Modulino.
-  The supported notes are defined as follows:
-  - B0
-  - C1, CS1, D1, DS1, E1, F1, FS1, G1, GS1, A1, AS1, B1
-  - C2, CS2, D2, DS2, E2, F2, FS2, G2, GS2, A2, AS2, B2
-  - C3, CS3, D3, DS3, E3, F3, FS3, G3, GS3, A3, AS3, B3
-  - C4, CS4, D4, DS4, E4, F4, FS4, G4, GS4, A4, AS4, B4
-  - C5, CS5, D5, DS5, E5, F5, FS5, G5, GS5, A5, AS5, B5
-  - C6, CS6, D6, DS6, E6, F6, FS6, G6, GS6, A6, AS6, B6
-  - C7, CS7, D7, DS7, E7, F7, FS7, G7, GS7, A7, AS7, B7
-  - C8, CS8, D8, DS8
-  - REST (Silence)
-
-  Those notes are accessible through ModulinoBuzzer.NOTES e.g. ModulinoBuzzer.NOTES["C4"]
+  Class to play tones on the piezo element of the Modulino Buzzer.
+  Predefined notes are available in the NOTES dictionary e.g. ModulinoBuzzer.NOTES["C4"]
   """
+
   NOTES = {
     "B0": 31,
     "C1": 33,
@@ -110,6 +99,20 @@ class ModulinoBuzzer(Modulino):
     "DS8": 4978,
     "REST": 0
   }
+  """
+  Dictionary with the notes and their corresponding frequencies.
+  The supported notes are defined as follows:
+  - B0
+  - C1, CS1, D1, DS1, E1, F1, FS1, G1, GS1, A1, AS1, B1
+  - C2, CS2, D2, DS2, E2, F2, FS2, G2, GS2, A2, AS2, B2
+  - C3, CS3, D3, DS3, E3, F3, FS3, G3, GS3, A3, AS3, B3
+  - C4, CS4, D4, DS4, E4, F4, FS4, G4, GS4, A4, AS4, B4
+  - C5, CS5, D5, DS5, E5, F5, FS5, G5, GS5, A5, AS5, B5
+  - C6, CS6, D6, DS6, E6, F6, FS6, G6, GS6, A6, AS6, B6
+  - C7, CS7, D7, DS7, E7, F7, FS7, G7, GS7, A7, AS7, B7
+  - C8, CS8, D8, DS8
+  - REST (Silence)
+  """
 
   default_addresses = [0x3C]
 

src/modulino/distance.py

@@ -2,6 +2,10 @@
 from .lib.vl53l4cd import VL53L4CD
 
 class ModulinoDistance(Modulino):
+    """
+    Class to interact with the distance sensor of the Modulino Distance.
+    """
+
     default_addresses = [0x29]
     convert_default_addresses = False
 
@@ -14,13 +18,23 @@ def __init__(self, i2c_bus = None, address: int | None = None) -> None:
 
     @property
     def _distance_raw(self):
+        """
+        Reads the raw distance value from the sensor and clears the interrupt.
+
+        Returns:
+            int: The distance in centimeters.
+        """
         while not self.sensor.data_ready:
             pass
         self.sensor.clear_interrupt()
         return self.sensor.distance
 
     @property
     def distance(self):
+        """
+        Returns:
+            int: The distance in centimeters.
+        """
         while True:
             raw_distance = self._distance_raw
             # Filter out invalid readings

src/modulino/knob.py

@@ -1,6 +1,9 @@
 from .modulino import Modulino
 
 class ModulinoKnob(Modulino):
+  """
+  Class to interact with the rotary encoder of the Modulinio Knob.
+  """
 
   # This module can have one of two default addresses
   # This is for a use case where two encoders are bundled together in a package
@@ -36,19 +39,42 @@ def __init__(self, i2c_bus=None, address=None):
     self._encoder_value = None
     self._pressed_status = None
 
-  def _has_rotated_clockwise(self, previous_value, current_value):
+  def _has_rotated_clockwise(self, previous_value, current_value) -> bool:
+    """
+    Determines if the encoder has rotated clockwise.
+
+    Parameters:
+        previous_value (int): The previous value of the encoder.
+        current_value (int): The current value of the encoder.
+
+    Returns:
+        bool: True if the encoder has rotated clockwise.
+    """
     # Calculate difference considering wraparound
     diff = (current_value- previous_value + 65536) % 65536
     # Clockwise rotation is indicated by a positive difference less than half the range
     return 0 < diff < 32768
 
-  def _has_rotated_counter_clockwise(self, previous_value, current_value):
+  def _has_rotated_counter_clockwise(self, previous_value, current_value) -> bool:
+      """
+      Determines if the encoder has rotated counter clockwise.
+
+      Parameters:
+          previous_value (int): The previous value of the encoder.
+          current_value (int): The current value of the encoder.
+
+      Returns:
+          bool: True if the encoder has rotated counter clockwise.
+      """
       # Calculate difference considering wraparound
       diff = (previous_value - current_value+ 65536) % 65536
       # Counter-clockwise rotation is indicated by a positive difference less than half the range
       return 0 < diff < 32768
 
-  def _get_steps(self, previous_value, current_value):
+  def _get_steps(self, previous_value, current_value) -> int:
+    """
+    Calculates the number of steps the encoder has moved since the last update.
+    """
     # Calculate difference considering wraparound
     diff = (current_value - previous_value + 65536) % 65536
     # Clockwise rotation is indicated by a positive difference less than half the range
@@ -61,6 +87,11 @@ def _get_steps(self, previous_value, current_value):
       return 0
 
   def _read_data(self):
+    """
+    Reads the encoder value and pressed status from the Modulino.
+    Adjusts the value to the range if it is set.
+    Converts the encoder value to a signed 16-bit integer.
+    """
     data = self.read(3)
     self._pressed = data[2] != 0
     self._encoder_value = int.from_bytes(data[0:2], 'little', True)
@@ -82,10 +113,13 @@ def reset(self):
     """
     self.value = 0
 
-  def update(self):
+  def update(self) -> bool:
     """
     Reads new data from the Modulino and calls the corresponding callbacks 
     if the encoder value or pressed status has changed.
+
+    Returns:
+        bool: True if the encoder value or pressed status has changed.
     """
     previous_value = self._encoder_value
     previous_pressed_status = self._pressed
@@ -117,7 +151,7 @@ def update(self):
     return (self._encoder_value != previous_value) or (self._pressed != previous_pressed_status)
 
   @property
-  def range(self):
+  def range(self) -> tuple[int, int]:
     """
     Returns the range of the encoder value.
     """    
@@ -146,7 +180,7 @@ def range(self, value):
       self.value = self._value_range[1]
 
   @property
-  def on_rotate_clockwise(self):
+  def on_rotate_clockwise(self) -> function:
     """
     Returns the callback for the rotate clockwise event.
     """
@@ -163,7 +197,7 @@ def on_rotate_clockwise(self, value):
     self._on_rotate_clockwise = value
 
   @property
-  def on_rotate_counter_clockwise(self):
+  def on_rotate_counter_clockwise(self) -> function:
     """
     Returns the callback for the rotate counter clockwise event.
     """
@@ -180,7 +214,7 @@ def on_rotate_counter_clockwise(self, value):
     self._on_rotate_counter_clockwise = value
 
   @property
-  def on_press(self):
+  def on_press(self) -> function:
     """
     Returns the callback for the press event.
     """
@@ -197,7 +231,7 @@ def on_press(self, value):
     self._on_press = value
 
   @property
-  def on_release(self):
+  def on_release(self) -> function:
     """
     Returns the callback for the release event.
     """
@@ -214,7 +248,7 @@ def on_release(self, value):
     self._on_release = value
 
   @property
-  def value(self):
+  def value(self) -> int:
     """
     Returns the current value of the encoder.
     """
@@ -244,7 +278,7 @@ def value(self, new_value):
       self._encoder_value = new_value
 
   @property
-  def pressed(self):
+  def pressed(self) -> bool:
     """
     Returns the pressed status of the encoder.
     """