Update API docs

Author: sebromero

src/modulino/buttons.py

@@ -26,6 +26,14 @@ def __init__(self, i2c_bus=None, address=None):
     self._on_button_c_long_press = None
 
   def set_led_status(self, a, b, c):
+    """
+    Turn on or off the button LEDs according to the given status.
+
+    Parameters:
+      a (bool): The status of the LED A.
+      b (bool): The status of the LED B.
+      c (bool): The status of the LED C.
+    """
     data = bytearray(3)
     data[0] = 1 if a else 0
     data[1] = 1 if b else 0
@@ -116,6 +124,9 @@ def update(self):
     """
     Update the button status and call the corresponding callbacks.
     Returns True if any of the buttons has changed its state.
+
+    Returns:
+      bool: True if any of the buttons has changed its state.
     """
     new_status = self.read(3)
     button_states_changed = new_status != self._current_buttons_status
@@ -168,6 +179,12 @@ def update(self):
     return button_states_changed
 
   def is_pressed(self, index):
+    """
+    Returns True if the button at the given index is currently pressed.
+
+    Parameters:
+      index (int): The index of the button. A = 0, B = 1, C = 2.
+    """
     return self._current_buttons_status[index]
 
   @property

src/modulino/buzzer.py

@@ -103,6 +103,15 @@ def __init__(self, i2c_bus = None, address = None):
     self.no_tone()
 
   def tone(self, frequency, lenght_ms=0xFFFF, blocking=False):
+    """
+    Plays a tone with the given frequency and duration.
+    If blocking is set to True, the function will wait until the tone is finished.
+
+    Parameters:
+      frequency: The frequency of the tone in Hz
+      lenght_ms: The duration of the tone in milliseconds
+      blocking: If set to True, the function will wait until the tone is finished
+    """
     self.data[0:4]=frequency.to_bytes(4,'little')
     self.data[4:8]=lenght_ms.to_bytes(4,'little')
     self.write(self.data)
@@ -113,5 +122,8 @@ def tone(self, frequency, lenght_ms=0xFFFF, blocking=False):
       sleep_ms(lenght_ms - 5)
 
   def no_tone(self):
+    """
+    Stops the current tone from playing.
+    """
     self.data = bytearray(8)
     self.write(self.data)

src/modulino/knob.py

@@ -77,9 +77,16 @@ def _read_data(self):
         self.value = constrained_value
 
   def reset(self):
+    """
+    Resets the encoder value to 0.
+    """
     self.value = 0
 
   def update(self):
+    """
+    Reads new data from the Modulino and calls the corresponding callbacks 
+    if the encoder value or pressed status has changed.
+    """
     previous_value = self._encoder_value
     previous_pressed_status = self._pressed
 
@@ -115,6 +122,12 @@ def range(self):
 
   @range.setter
   def range(self, value):
+    """
+    Sets the range of the encoder value.
+
+    Parameters:
+      value (tuple): A tuple with two integers representing the minimum and maximum values of the range.
+    """
     if(value[0] < -32768 or value[1] > 32767):
       raise ValueError("Range must be between -32768 and 32767")
 
@@ -135,6 +148,12 @@ def on_rotate_clockwise(self):
 
   @on_rotate_clockwise.setter
   def on_rotate_clockwise(self, value):
+    """
+    Sets the callback for the rotate clockwise event.
+
+    Parameters:
+      value (function): The function to be called when the encoder is rotated clockwise.
+    """
     self._on_rotate_clockwise = value
 
   @property
@@ -143,6 +162,12 @@ def on_rotate_counter_clockwise(self):
 
   @on_rotate_counter_clockwise.setter
   def on_rotate_counter_clockwise(self, value):
+    """
+    Sets the callback for the rotate counter clockwise event.
+
+    Parameters:
+      value (function): The function to be called when the encoder is rotated counter clockwise.
+    """
     self._on_rotate_counter_clockwise = value
 
   @property
@@ -151,6 +176,12 @@ def on_press(self):
 
   @on_press.setter
   def on_press(self, value):
+    """
+    Sets the callback for the press event.
+
+    Parameters:
+      value (function): The function to be called when the encoder is pressed.
+    """
     self._on_press = value
 
   @property
@@ -159,14 +190,29 @@ def on_release(self):
 
   @on_release.setter
   def on_release(self, value):
+    """
+    Sets the callback for the release event.
+
+    Parameters:
+      value (function): The function to be called when the encoder is released.
+    """
     self._on_release = value
 
   @property
   def value(self):
+    """
+    Returns the current value of the encoder.
+    """
     return self._encoder_value
 
   @value.setter
   def value(self, new_value):
+    """
+    Sets the value of the encoder. This overrides the previous value.
+
+    Parameters:
+      new_value (int): The new value of the encoder.
+    """
     if(self._value_range != None): 
       if(new_value < self._value_range[0]) or (new_value > self._value_range[1]):
         raise ValueError(f"Value {new_value} is out of range ({self._value_range[0]} to {self._value_range[1]})")
@@ -184,4 +230,7 @@ def value(self, new_value):
 
   @property
   def pressed(self):
+    """
+    Returns the pressed status of the encoder.
+    """
     return self._pressed

src/modulino/pixels.py

@@ -35,19 +35,63 @@ def _mapi(self, x, in_min, in_max, out_min, out_max) -> int:
     return int(self._map(x, in_min, in_max, out_min, out_max)) 
 
   def set_range_rgb(self, index_from, index_to, r, g, b, brightness=100):
+    """
+    Sets the color of the LEDs in the given range to the given RGB values.
+
+    Parameters:
+      index_from (int): The starting index of the range.
+      index_to (int): The ending index (inclusive) of the range.
+      r (int): The red value of the color.
+      g (int): The green value of the color.
+      b (int): The blue value of the color.
+      brightness (int): The brightness of the LED. It should be a value between 0 and 100.
+    """
     self.set_range_color(index_from, index_to, ModulinoColor(r, g, b), brightness)
 
   def set_range_color(self, index_from, index_to, color, brightness=100):
+    """
+    Sets the color of the LEDs in the given range to the given color.
+
+    Parameters:
+      index_from (int): The starting index of the range.
+      index_to (int): The ending index (inclusive) of the range.
+      color (ModulinoColor): The color of the LEDs.
+      brightness (int): The brightness of the LED. It should be a value between 0 and 100.
+    """
     for i in range(index_from, index_to + 1):
       self.set_color(i, color, brightness)
 
   def set_all_rgb(self, r, g, b, brightness=100):
+    """
+    Sets the color of all the LEDs to the given RGB values.
+
+    Parameters:
+      r (int): The red value of the color.
+      g (int): The green value of the color.
+      b (int): The blue value of the color.
+      brightness (int): The brightness of the LED. It should be a value between 0 and 100.
+    """
     self.set_all_color(ModulinoColor(r, g, b), brightness)
 
   def set_all_color(self, color, brightness=100):
+    """
+    Sets the color of all the LEDs to the given color.
+
+    Parameters:
+      color (ModulinoColor): The color of the LEDs.
+      brightness (int): The brightness of the LED. It should be a value between 0 and 100.
+    """
     self.set_range_color(0, NUM_LEDS - 1, color, brightness)
 
   def set_color(self, idx, rgb : ModulinoColor , brightness=100):
+    """
+    Sets the color of the given LED index to the given color.
+
+    Parameters:
+      idx (int): The index of the LED.
+      rgb (ModulinoColor): The color of the LED.
+      brightness (int): The brightness of the LED. It should be a value between 0 and 100.
+    """
     if idx < 0 or idx >= NUM_LEDS:
       raise ValueError(f"LED index out of range {idx} (Valid: 0..{NUM_LEDS - 1})")
 
@@ -57,17 +101,43 @@ def set_color(self, idx, rgb : ModulinoColor , brightness=100):
     self.data[byte_index: byte_index+4] = color_data_bytes.to_bytes(4, 'little')
 
   def set_rgb(self, idx, r, g, b, brightness=100):
+    """
+    Set the color of the given LED index to the given RGB values.
+
+    Parameters:
+      idx (int): The index of the LED.
+      r (int): The red value of the color.
+      g (int): The green value of the color.
+      b (int): The blue value of the color.
+      brightness (int): The brightness of the LED. It should be a value between 0 and 100.
+    """
     self.set_color(idx, ModulinoColor(r, g, b), brightness)
 
   def clear(self, idx):
+    """
+    Turns off the LED at the given index.
+
+    Parameters:
+      idx (int): The index of the LED.
+    """
     self.set_color(idx, ModulinoColor(0, 0, 0), 0)
 
   def clear_range(self, start, end):
     for i in range(start, end):
         self.clear(i)
 
   def clear_all(self):
+    """
+    Turns all the LEDs off.
+
+    Parameters:
+      idx (int): The index of the LED
+    """
     self.data = bytearray([0xE0] * NUM_LEDS * 4)
 
   def show(self):
+    """
+    Applies the changes to the LEDs. This function needs to be called after any changes to the LEDs.
+    Otherwise, the changes will not be visible.
+    """
     self.write(self.data)