doc updates

docs/api.rst

@@ -3,14 +3,43 @@ picozero API
 
 .. module:: picozero
 
-Button
-------
-
 LED
 ---
 
 .. autofunction:: LED
 
+DigitalLED
+----------
+
+.. autoclass:: DigitalLED
+    :show-inheritance:
+    :inherited-members:
+    :members:
+
+PWMLED
+----------
+
+.. autoclass:: PWMLED
+    :show-inheritance:
+    :inherited-members:
+    :members:
+
+Button
+------
+
+.. autoclass:: Button
+    :show-inheritance:
+    :inherited-members:
+    :members:
+
+Switch
+------
+
+.. autoclass:: Switch
+    :show-inheritance:
+    :inherited-members:
+    :members: 
+
 
 RGBLED
 ------
@@ -22,15 +51,8 @@ Speaker
 -------
 
 Potentiometer
---------------
+-------------
 
 TemperatureSensor
 -----------------
 
-DigitalLED
-----------
-
-.. autoclass:: DigitalLED
-    :show-inheritance:
-    :inherited-members:
-    :members:

docs/examples/led_on_off.py

@@ -3,7 +3,6 @@
 
 led = LED(14)
 
-while True:
-    led.toggle()
-    sleep(1)
-
+led.on()
+sleep(1)
+led.off()

docs/examples/led_toggle.py

@@ -0,0 +1,9 @@
+from picozero import LED
+from time import sleep
+
+led = LED(14)
+
+while True:
+    led.toggle()
+    sleep(1)
+

docs/recipes.rst

@@ -148,7 +148,7 @@ Control a passive buzzer or speaker that can play different tones or frequencies
 .. literalinclude:: examples/speaker.py
 
 Internal Temperature Sensor
------------------------
+---------------------------
 
 Check the internal temperature of the Raspberry Pi Pico in degrees Celcius:
 

picozero/__init__.py

@@ -7,6 +7,7 @@
     LED,
     DigitalInputDevice,
     Button,
+    Switch,
     RGBLED,
     AnalogInputDevice,
     Potentiometer,

picozero/picozero.py

@@ -67,14 +67,22 @@ def stop(self):
         self._timer.deinit()
 
 class OutputDevice:
-
+    """
+    Base class for output devices. 
+    """   
     def __init__(self, active_high=True, initial_value=False):
         self.active_high = active_high
         self._write(initial_value)
         self._value_changer = None
 
     @property
     def active_high(self):
+        """
+        Sets or returns the active_high property. If :data:`True`, the 
+        :meth:`on` method will set the Pin to HIGH. If :data:`False`, 
+        the :meth:`on` method will set the Pin toLOW (the :meth:`off` method 
+        always does the opposite).
+        """
         return self._active_state
 
     @active_high.setter
@@ -109,7 +117,7 @@ def off(self):
     @property
     def is_active(self):
         """
-        Returns :data:`True` is the device is on.
+        Returns :data:`True` if the device is on.
         """
         return bool(self.value)
 
@@ -171,6 +179,10 @@ def _write(self, value):
         self._pin.value(self._value_to_state(value))
 
     def close(self):
+        """
+        Closes the device and turns the device off. Once closed, the device
+        can no longer be used.
+        """
         super().close()
         self._pin = None
 
@@ -234,9 +246,16 @@ def _write(self, value):
 
     @property
     def is_active(self):
+        """
+        Returns :data:`True` if the device is on.
+        """
         return self.value != 0
 
     def close(self):
+        """
+        Closes the device and turns the device off. Once closed, the device
+        can no longer be used.
+        """
         super().close()
         del PWMOutputDevice._channels_used[
             PWMOutputDevice.PIN_TO_PWM_CHANNEL[self._pin_num]
@@ -393,11 +412,21 @@ def LED(pin, use_pwm=True, active_high=True, initial_value=False):
 pico_led = LED(25)
 
 class InputDevice:
+    """
+    Base class for input devices.
+    """
     def __init__(self, active_state=None):
         self._active_state = active_state
 
     @property
     def active_state(self):
+        """
+        Sets or returns the active state of the device. If :data:`None` (the default),
+        the device will return the value that the pin is set to. If
+        :data:`True`, the device will return :data:`True` if the pin is
+        HIGH. If :data:`False`, the device will return :data:`False` if the
+        pin is LOW.
+        """
         return self._active_state
 
     @active_state.setter
@@ -407,9 +436,32 @@ def active_state(self, value):
 
     @property
     def value(self):
+        """
+        Returns the current value of the device. This is either :data:`True` 
+        or :data:`False` depending on the value of :attr:`active_state`.
+        """
         return self._read()
 
 class DigitalInputDevice(InputDevice):
+    """
+    :param int pin:
+        The pin that the device is connected to.
+
+    :param bool pull_up:
+        If :data:`True` (the default), the device will be pulled up to
+        HIGH. If :data:`False`, the device will be pulled down to LOW.
+
+    :param bool active_state:
+        If :data:`True` (the default), the device will return :data:`True`
+        if the pin is HIGH. If :data:`False`, the device will return
+        :data:`False` if the pin is LOW.
+
+    :param float bounce_time:
+        The bounce time for the device. If set, the device will ignore
+        any button presses that happen within the bounce time after a
+        button release. This is useful to prevent accidental button
+        presses from registering as multiple presses.
+    """
     def __init__(self, pin, pull_up=False, active_state=None, bounce_time=None):
         super().__init__(active_state)
         self._pin = Pin(
@@ -468,14 +520,23 @@ def _pin_change(self, p):
 
     @property
     def is_active(self):
+        """
+        Returns :data:`True` if the device is active.
+        """
         return bool(self.value)
 
     @property
     def is_inactive(self):
+        """
+        Returns :data:`True` if the device is inactive.
+        """
         return not bool(self.value)
 
     @property
     def when_activated(self):
+        """
+        Returns a :samp:`callback` that will be called when the device is activated.
+        """
         return self._when_activated
 
     @when_activated.setter
@@ -484,27 +545,48 @@ def when_activated(self, value):
 
     @property
     def when_deactivated(self):
+        """
+        Returns a :samp:`callback` that will be called when the device is deactivated.
+        """
         return self._when_deactivated
 
     @when_activated.setter
     def when_deactivated(self, value):
         self._when_deactivated = value
 
     def close(self):
+        """
+        Closes the device and releases any resources. Once closed, the device
+        can no longer be used.
+        """
         self._pin.irq(handler=None)
         self._pin = None
 
 
 class Switch(DigitalInputDevice):
-    def __init__(self, pin, pull_up=True, bounce_time=0.02):
+    """
+    :param int pin:
+        The pin that the device is connected to.
+
+    :param bool pull_up:
+        If :data:`True` (the default), the device will be pulled up to
+        HIGH. If :data:`False`, the device will be pulled down to LOW.
+
+    :param float bounce_time:
+        The bounce time for the device. If set, the device will ignore
+        any button presses that happen within the bounce time after a
+        button release. This is useful to prevent accidental button
+        presses from registering as multiple presses. Defaults to 0.02 
+        seconds.
+    """
+    def __init__(self, pin, pull_up=True, bounce_time=0.02): 
         super().__init__(pin=pin, pull_up=pull_up, bounce_time=bounce_time)
 
 Switch.is_closed = Switch.is_active
 Switch.is_open = Switch.is_inactive
 Switch.when_closed = Switch.when_activated
 Switch.when_opened = Switch.when_deactivated
 
-
 class Button(Switch):
     pass