Merge pull request #44 from jepler/doc-improvements

Improve documentation

Author: ladyada

adafruit_seesaw/analoginput.py

@@ -21,10 +21,22 @@
 # THE SOFTWARE.
 # pylint: disable=missing-docstring,invalid-name,too-many-public-methods
 
+"""
+`adafruit_seesaw.analoginput`
+====================================================
+"""
+
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git"
 
 class AnalogInput:
+    """CircuitPython-compatible class for analog inputs
+
+    This class is intended to be a compatible subset of `analogio.AnalogIn`
+
+    :param ~adafruit_seesaw.seesaw.Seesaw seesaw: The device
+    :param int pin: The pin number on the device
+"""
     def __init__(self, seesaw, pin):
         self._seesaw = seesaw
         self._pin = pin
@@ -34,8 +46,10 @@ def deinit(self):
 
     @property
     def value(self):
+        """The current analog value on the pin, as an integer from 0..65535 (inclusive)"""
         return self._seesaw.analog_read(self._pin)
 
     @property
     def reference_voltage(self):
+        """The reference voltage for the pin"""
         return 3.3

adafruit_seesaw/crickit.py

@@ -21,7 +21,16 @@
 # THE SOFTWARE.
 # pylint: disable=missing-docstring,invalid-name,too-many-public-methods,too-few-public-methods
 
-from micropython import const
+"""
+`adafruit_seesaw.crickit` - Pin definition for Adafruit CRICKIT
+===============================================================
+"""
+
+try:
+    from micropython import const
+except ImportError:
+    def const(x):
+        return x
 
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git"

adafruit_seesaw/digitalio.py

@@ -21,12 +21,26 @@
 # THE SOFTWARE.
 # pylint: disable=missing-docstring,invalid-name,too-many-public-methods
 
+"""
+`adafruit_seesaw.digitalio`
+====================================================
+"""
+
 import digitalio
 
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git"
 
 class DigitalIO:
+    """CircuitPython-compatible class for digital I/O pins
+
+    This class is intended to be a compatible subset of `digitalio.DigitalInOut`.
+
+    Due to technical limitations, PULL_DOWNs are not supported.
+
+    :param ~adafruit_seesaw.seesaw.Seesaw seesaw: The device
+    :param int pin: The pin number on the device
+"""
     def __init__(self, seesaw, pin):
         self._seesaw = seesaw
         self._pin = pin
@@ -39,22 +53,25 @@ def deinit(self):
         pass
 
     def switch_to_output(self, value=False, drive_mode=digitalio.DriveMode.PUSH_PULL):
+        """Switch the pin to output mode"""
         self._seesaw.pin_mode(self._pin, self._seesaw.OUTPUT)
         self._seesaw.digital_write(self._pin, value)
         self._drive_mode = drive_mode
         self._pull = None
 
     def switch_to_input(self, pull=None):
+        """Switch the pin to input mode"""
         if pull == digitalio.Pull.DOWN:
             raise ValueError("Pull Down currently not supported")
-        elif pull == digitalio.Pull.UP:
+        if pull == digitalio.Pull.UP:
             self._seesaw.pin_mode(self._pin, self._seesaw.INPUT_PULLUP)
         else:
             self._seesaw.pin_mode(self._pin, self._seesaw.INPUT)
         self._pull = pull
 
     @property
     def direction(self):
+        """Retrieve or set the direction of the pin"""
         return self._direction
 
     @direction.setter
@@ -69,6 +86,7 @@ def direction(self, value):
 
     @property
     def value(self):
+        """Retrieve or set the value of the pin"""
         if self._direction == digitalio.Direction.OUTPUT:
             return self._value
         return self._seesaw.digital_read(self._pin)
@@ -82,6 +100,7 @@ def value(self, val):
 
     @property
     def drive_mode(self):
+        """Retrieve or set the drive mode of an output pin"""
         return self._drive_mode
 
     @drive_mode.setter
@@ -90,15 +109,16 @@ def drive_mode(self, mode):
 
     @property
     def pull(self):
+        """Retrieve or set the pull mode of an input pin"""
         return self._pull
 
     @pull.setter
     def pull(self, mode):
         if self._direction == digitalio.Direction.OUTPUT:
             raise AttributeError("cannot set pull on an output pin")
-        elif mode == digitalio.Pull.DOWN:
+        if mode == digitalio.Pull.DOWN:
             raise ValueError("Pull Down currently not supported")
-        elif mode == digitalio.Pull.UP:
+        if mode == digitalio.Pull.UP:
             self._seesaw.pin_mode(self._pin, self._seesaw.INPUT_PULLUP)
         elif mode is None:
             self._seesaw.pin_mode(self._pin, self._seesaw.INPUT)

adafruit_seesaw/keypad.py

@@ -21,7 +21,16 @@
 # THE SOFTWARE.
 # pylint: disable=missing-docstring,invalid-name,too-many-public-methods
 
-from micropython import const
+"""
+`adafruit_seesaw.keypad`
+====================================================
+"""
+
+try:
+    from micropython import const
+except ImportError:
+    def const(x):
+        return x
 from adafruit_seesaw.seesaw import Seesaw
 
 __version__ = "0.0.0-auto.0"
@@ -38,16 +47,30 @@
 
 # pylint: disable=too-few-public-methods
 class KeyEvent:
+    """Holds information about a key event in its properties
+
+       :param int num: The number of the key
+       :param int edge: One of the EDGE propertes of `adafruit_seesaw.keypad.Keypad`
+    """
     def __init__(self, num, edge):
         self.number = int(num)
         self.edge = int(edge)
 # pylint: enable=too-few-public-methods
 
 class Keypad(Seesaw):
+    """On compatible SeeSaw devices, reads from a keypad.
+
+       :param ~busio.I2C i2c_bus: Bus the SeeSaw is connected to
+       :param int addr: I2C address of the SeeSaw device
+       :param ~digitalio.DigitalInOut drdy: Pin connected to SeeSaw's 'ready' output"""
 
+    #: Indicates that the key is currently pressed
     EDGE_HIGH = 0
+    #: Indicates that the key is currently released
     EDGE_LOW = 1
+    #: Indicates that the key was recently pressed
     EDGE_FALLING = 2
+    #: Indicates that the key was recently released
     EDGE_RISING = 3
 
     def __init__(self, i2c_bus, addr=0x49, drdy=None):
@@ -56,6 +79,7 @@ def __init__(self, i2c_bus, addr=0x49, drdy=None):
 
     @property
     def interrupt_enabled(self):
+        """Retrieve or set the interrupt enable flag"""
         return self._interrupt_enabled
 
     @interrupt_enabled.setter
@@ -71,6 +95,7 @@ def interrupt_enabled(self, value):
 
     @property
     def count(self):
+        """Retrieve or set the number of keys"""
         return self.read8(_KEYPAD_BASE, _KEYPAD_COUNT)
 
     # pylint: disable=unused-argument, no-self-use
@@ -80,6 +105,12 @@ def count(self, value):
     # pylint: enable=unused-argument, no-self-use
 
     def set_event(self, key, edge, enable):
+        """Control which kinds of events are set
+
+           :param int key: The key number
+           :param int edge: The type of event
+           :param bool enable: True to enable the event, False to disable it"""
+
         if enable not in (True, False):
             raise ValueError("event enable must be True or False")
         if edge > 3 or edge < 0:
@@ -92,6 +123,9 @@ def set_event(self, key, edge, enable):
         self.write(_KEYPAD_BASE, _KEYPAD_EVENT, cmd)
 
     def read_keypad(self, num):
+        """Read data from the keypad
+
+        :param int num: The number of bytes to read"""
         ret = bytearray(num)
         self.read(_KEYPAD_BASE, _KEYPAD_FIFO, ret)
         return ret

adafruit_seesaw/neopixel.py

@@ -21,11 +21,20 @@
 # THE SOFTWARE.
 # pylint: disable=missing-docstring,invalid-name,too-many-public-methods
 
+"""
+`adafruit_seesaw.neopixel`
+====================================================
+"""
+
 try:
     import struct
 except ImportError:
     import ustruct as struct
-from micropython import const
+try:
+    from micropython import const
+except ImportError:
+    def const(x):
+        return x
 
 __version__ = "1.2.3"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git"
@@ -50,6 +59,17 @@
 """Green Red Blue White"""
 
 class NeoPixel:
+    """Control NeoPixels connected to a seesaw
+
+    :param ~adafruit_seesaw.seesaw.Seesaw seesaw: The device
+    :param int pin: The pin number on the device
+    :param int n: The number of pixels
+    :param int bpp: The number of bytes per pixel
+    :param float brightness: The brightness, from 0.0 to 1.0
+    :param bool auto_write: Automatically update the pixels when changed
+    :param tuple pixel_order: The layout of the pixels.
+        Use one of the order constants such as RGBW.
+"""
     def __init__(self, seesaw, pin, n, *, bpp=3, brightness=1.0, auto_write=True, pixel_order=None):
         # TODO: brightness not yet implemented.
         self._seesaw = seesaw
@@ -84,6 +104,7 @@ def __len__(self):
         return self._n
 
     def __setitem__(self, key, color):
+        """Set one pixel to a new value"""
         cmd = bytearray(2 + self._bpp)
         struct.pack_into(">H", cmd, 0, key * self._bpp)
         if isinstance(color, int):
@@ -127,6 +148,7 @@ def __getitem__(self, key):
         pass
 
     def fill(self, color):
+        """Set all pixels to the same value"""
         # Suppress auto_write while filling.
         current_auto_write = self.auto_write
         self.auto_write = False
@@ -137,4 +159,5 @@ def fill(self, color):
         self.auto_write = current_auto_write
 
     def show(self):
+        """Update the pixels even if auto_write is False"""
         self._seesaw.write(_NEOPIXEL_BASE, _NEOPIXEL_SHOW)

adafruit_seesaw/pwmout.py

@@ -21,6 +21,11 @@
 # THE SOFTWARE.
 # pylint: disable=missing-docstring,invalid-name,too-many-public-methods,too-few-public-methods
 
+"""
+`adafruit_seesaw.pwmout`
+====================================================
+"""
+
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git"
 
@@ -34,7 +39,7 @@ def __init__(self, seesaw, pin):
 
     @property
     def frequency(self):
-        """The overall PWM frequency in herz."""
+        """The overall PWM frequency in Hertz."""
         return self._frequency
 
     @frequency.setter

adafruit_seesaw/robohat.py

@@ -21,7 +21,16 @@
 # THE SOFTWARE.
 # pylint: disable=missing-docstring,invalid-name,too-many-public-methods,too-few-public-methods
 
-from micropython import const
+"""
+`adafruit_seesaw.robohat` - Pin definition for RoboHAT
+======================================================
+"""
+
+try:
+    from micropython import const
+except ImportError:
+    def const(x):
+        return x
 
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git"
@@ -73,22 +82,30 @@
 # PB<nn> pins are 32+nn
 
 class MM1_Pinmap:
+    """This class is automatically used by `adafruit_seesaw.seesaw.Seesaw` when
+    a RoboHAT board is detected.
+
+    It is also a reference for the capabilities of each pin."""
     # seesaw firmware (mm1_hat) analog pin map:
     # analog[0]:47    analog[1]:48    analog[2]:     analog[3]:
     # analog[4]:    analog[5]:    analog[6]:    analog[7]:
     #
+    #: The pins capable of analog output
     analog_pins = (_MM1_D3, _MM1_D2)
 
+    #: The effective bit resolution of the PWM pins
     pwm_width = 16
 
     # seesaw firmware (mm1_hat) pwm pin map:
     # pwm[0]:16   pwm[1]:17    pwm[2]:18    pwm[3]:19    pwm[4]:11    pwm[5]:10
     # pwm[6]:9    pwm[7]:8    pwm[8]:40    pwm[9]:41    pwm[10]:42   pwm[11]:43
     #
+    #: The pins capable of PWM output
     pwm_pins = (_MM1_SERVO1, _MM1_SERVO2, _MM1_SERVO3, _MM1_SERVO4,
                 _MM1_SERVO5, _MM1_SERVO6, _MM1_SERVO7, _MM1_SERVO8,
                 _MM1_D12, _MM1_D10, _MM1_D11, _MM1_D9)
 
     # seesaw firmware touch pin map:
     # touch[0]: 7    touch[1]: 6    touch[2]: 5    touch[3]: 4
+    #: The pins capable of touch input
     touch_pins = (_MM1_RCH1, _MM1_RCH2, _MM1_RCH3, _MM1_RCH4)

adafruit_seesaw/samd09.py

@@ -21,7 +21,16 @@
 # THE SOFTWARE.
 # pylint: disable=missing-docstring,invalid-name,too-many-public-methods,too-few-public-methods
 
-from micropython import const
+"""
+`adafruit_seesaw.samd09` - Pin definition for Adafruit SAMD09 Breakout with seesaw
+==================================================================================
+"""
+
+try:
+    from micropython import const
+except ImportError:
+    def const(x):
+        return x
 
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git"
@@ -37,11 +46,20 @@
 _PWM_3_PIN = const(0x07)
 
 class SAMD09_Pinmap:
+    """This class is automatically used by `adafruit_seesaw.seesaw.Seesaw` when
+    a SAMD09 Breakout is detected.
+
+    It is also a reference for the capabilities of each pin."""
+
+    #: The pins capable of analog output
     analog_pins = (_ADC_INPUT_0_PIN, _ADC_INPUT_1_PIN,
                    _ADC_INPUT_2_PIN, _ADC_INPUT_3_PIN)
 
+    """The effective bit resolution of the PWM pins"""
     pwm_width = 8
 
+    """The pins capable of PWM output"""
     pwm_pins = (_PWM_0_PIN, _PWM_1_PIN, _PWM_2_PIN, _PWM_3_PIN)
 
+    """No pins on this board are capable of touch input"""
     touch_pins = ()