Merge pull request #95 from tekktrik/doc/update-documentation

Updates to Documentation

Author: FoamyGuy

adafruit_ht16k33/bargraph.py

@@ -36,7 +36,7 @@ def __getitem__(self, key: int) -> Optional[bool]:
         # construct the color value and return it
         return self._pixel(x, y) | self._pixel(x + 8, y) << 1
 
-    def __setitem__(self, key: int, value: bool):
+    def __setitem__(self, key: int, value: bool) -> None:
         # map to HT16K33 row (x) and column (y), see schematic
         x = key % 4 + 4 * (key // 12)
         y = key // 4 - 3 * (key // 12)
@@ -45,8 +45,12 @@ def __setitem__(self, key: int, value: bool):
         # conditionally turn on green LED
         self._pixel(x + 8, y, value >> 1)
 
-    def fill(self, color: bool):
-        """Fill the whole display with the given color."""
+    def fill(self, color: bool) -> None:
+        """Fill the whole display with the given color.
+
+        :param bool color: Whether to fill the display
+        """
+
         what_it_was = self.auto_write
         self.auto_write = False
         for i in range(24):

adafruit_ht16k33/ht16k33.py

@@ -33,6 +33,7 @@ class HT16K33:
     """
     The base class for all displays. Contains common methods.
 
+    :param I2C i2c: The I2C bus object
     :param int address: The I2C addess of the HT16K33.
     :param bool auto_write: True if the display should immediately change when
         set. If False, `show` must be called explicitly.
@@ -45,7 +46,7 @@ def __init__(
         address: int = 0x70,
         auto_write: bool = True,
         brightness: float = 1.0,
-    ):
+    ) -> None:
         self.i2c_device = i2c_device.I2CDevice(i2c, address)
         self._temp = bytearray(1)
         self._buffer = bytearray(17)
@@ -57,31 +58,31 @@ def __init__(
         self.blink_rate = 0
         self.brightness = brightness
 
-    def _write_cmd(self, byte: bytearray):
+    def _write_cmd(self, byte: bytearray) -> None:
         self._temp[0] = byte
         with self.i2c_device:
             self.i2c_device.write(self._temp)
 
     @property
-    def blink_rate(self):
+    def blink_rate(self) -> int:
         """The blink rate. Range 0-3."""
         return self._blink_rate
 
     @blink_rate.setter
-    def blink_rate(self, rate: int = None):
+    def blink_rate(self, rate: Optional[int] = None) -> None:
         if not 0 <= rate <= 3:
             raise ValueError("Blink rate must be an integer in the range: 0-3")
         rate = rate & 0x03
         self._blink_rate = rate
         self._write_cmd(_HT16K33_BLINK_CMD | _HT16K33_BLINK_DISPLAYON | rate << 1)
 
     @property
-    def brightness(self):
+    def brightness(self) -> float:
         """The brightness. Range 0.0-1.0"""
         return self._brightness
 
     @brightness.setter
-    def brightness(self, brightness: float):
+    def brightness(self, brightness: float) -> None:
         if not 0.0 <= brightness <= 1.0:
             raise ValueError(
                 "Brightness must be a decimal number in the range: 0.0-1.0"
@@ -93,26 +94,30 @@ def brightness(self, brightness: float):
         self._write_cmd(_HT16K33_CMD_BRIGHTNESS | xbright)
 
     @property
-    def auto_write(self):
+    def auto_write(self) -> bool:
         """Auto write updates to the display."""
         return self._auto_write
 
     @auto_write.setter
-    def auto_write(self, auto_write: bool):
+    def auto_write(self, auto_write: bool) -> None:
         if isinstance(auto_write, bool):
             self._auto_write = auto_write
         else:
             raise ValueError("Must set to either True or False.")
 
-    def show(self):
+    def show(self) -> None:
         """Refresh the display and show the changes."""
         with self.i2c_device:
             # Byte 0 is 0x00, address of LED data register. The remaining 16
             # bytes are the display register data to set.
             self.i2c_device.write(self._buffer)
 
-    def fill(self, color: bool):
-        """Fill the whole display with the given color."""
+    def fill(self, color: bool) -> None:
+        """Fill the whole display with the given color.
+
+        :param bool color: Whether to fill the display
+        """
+
         fill = 0xFF if color else 0x00
         for i in range(16):
             self._buffer[i + 1] = fill
@@ -134,7 +139,7 @@ def _pixel(self, x: int, y: int, color: Optional[bool] = None) -> Optional[bool]
             self.show()
         return None
 
-    def _set_buffer(self, i: int, value: bool):
+    def _set_buffer(self, i: int, value: bool) -> None:
         self._buffer[i + 1] = value  # Offset by 1 to move past register address.
 
     def _get_buffer(self, i: int) -> bool:

adafruit_ht16k33/matrix.py

@@ -4,8 +4,8 @@
 # SPDX-License-Identifier: MIT
 
 """
-Matrix Displays
-================
+adafruit_ht16k33.matrix
+=======================
 
 """
 from adafruit_ht16k33.ht16k33 import HT16K33
@@ -27,7 +27,14 @@ class Matrix8x8(HT16K33):
     _rows = 8
 
     def pixel(self, x: int, y: int, color: Optional[bool] = None) -> Optional[bool]:
-        """Get or set the color of a given pixel."""
+        """Get or set the color of a given pixel.
+
+        :param int x: The x coordinate of the pixel
+        :param int y: The y coordinate of the pixel
+        :param bool color: (Optional) The state to set the pixel
+        :return: If ``color`` was not set, this returns the state of the pixel
+        :rtype: bool
+        """
         if not 0 <= x <= 7:
             return None
         if not 0 <= y <= 7:
@@ -39,16 +46,18 @@ def __getitem__(self, key: int) -> Optional[bool]:
         x, y = key
         return self.pixel(x, y)
 
-    def __setitem__(self, key: int, value: bool):
+    def __setitem__(self, key: int, value: bool) -> None:
         x, y = key
         self.pixel(x, y, value)
 
     # pylint: disable=too-many-branches
-    def shift(self, x: int, y: int, rotate: bool = False):
+    def shift(self, x: int, y: int, rotate: bool = False) -> None:
         """
         Shift pixels by x and y
 
-        :param rotate: (Optional) Rotate the shifted pixels to the left side (default=False)
+        :param int x: The x coordinate of the pixel
+        :param int y: The y coordinate of the pixel
+        :param bool rotate: (Optional) Rotate the shifted pixels to the left side (default=False)
         """
         auto_write = self.auto_write
         self._auto_write = False
@@ -86,41 +95,45 @@ def shift(self, x: int, y: int, rotate: bool = False):
 
     # pylint: enable=too-many-branches
 
-    def shift_right(self, rotate: bool = False):
+    def shift_right(self, rotate: bool = False) -> None:
         """
         Shift all pixels right
 
         :param rotate: (Optional) Rotate the shifted pixels to the left side (default=False)
         """
         self.shift(1, 0, rotate)
 
-    def shift_left(self, rotate: bool = False):
+    def shift_left(self, rotate: bool = False) -> None:
         """
         Shift all pixels left
 
         :param rotate: (Optional) Rotate the shifted pixels to the right side (default=False)
         """
         self.shift(-1, 0, rotate)
 
-    def shift_up(self, rotate: bool = False):
+    def shift_up(self, rotate: bool = False) -> None:
         """
         Shift all pixels up
 
         :param rotate: (Optional) Rotate the shifted pixels to bottom (default=False)
         """
         self.shift(0, 1, rotate)
 
-    def shift_down(self, rotate: bool = False):
+    def shift_down(self, rotate: bool = False) -> None:
         """
         Shift all pixels down
 
         :param rotate: (Optional) Rotate the shifted pixels to top (default=False)
         """
         self.shift(0, -1, rotate)
 
-    def image(self, img):
+    def image(self, img: Image) -> None:
         """Set buffer to value of Python Imaging Library image.  The image should
-        be in 1 bit mode and a size equal to the display size."""
+        be in 1 bit mode and a size equal to the display size.
+
+        :param Image img: The image to show
+        """
+
         imwidth, imheight = img.size
         if imwidth != self.columns or imheight != self.rows:
             raise ValueError(
@@ -141,12 +154,12 @@ def image(self, img):
             self.show()
 
     @property
-    def columns(self):
+    def columns(self) -> int:
         """Read-only property for number of columns"""
         return self._columns
 
     @property
-    def rows(self):
+    def rows(self) -> int:
         """Read-only property for number of rows"""
         return self._rows
 
@@ -156,8 +169,16 @@ class Matrix16x8(Matrix8x8):
 
     _columns = 16
 
-    def pixel(self, x, y, color=None):
-        """Get or set the color of a given pixel."""
+    def pixel(self, x: int, y: int, color: Optional[bool] = None) -> Optional[bool]:
+        """Get or set the color of a given pixel.
+
+        :param int x: The x coordinate of the pixel
+        :param int y: The y coordinate of the pixel
+        :param bool color: (Optional) The state to set the pixel
+        :return: If ``color`` was not set, this returns the state of the pixel
+        :rtype: bool
+        """
+
         if not 0 <= x <= 15:
             return None
         if not 0 <= y <= 7:
@@ -171,8 +192,16 @@ def pixel(self, x, y, color=None):
 class MatrixBackpack16x8(Matrix16x8):
     """A double matrix backpack."""
 
-    def pixel(self, x, y, color=None):
-        """Get or set the color of a given pixel."""
+    def pixel(self, x: int, y: int, color: Optional[bool] = None) -> Optional[bool]:
+        """Get or set the color of a given pixel.
+
+        :param int x: The x coordinate of the pixel
+        :param int y: The y coordinate of the pixel
+        :param bool color: (Optional) The state to set the pixel
+        :return: If ``color`` was not set, this returns the state of the pixel
+        :rtype: bool
+        """
+
         if not 0 <= x <= 15:
             return None
         if not 0 <= y <= 7:
@@ -188,8 +217,15 @@ class Matrix8x8x2(Matrix8x8):
     LED_GREEN = 2
     LED_YELLOW = 3
 
-    def pixel(self, x, y, color=None):
-        """Get or set the color of a given pixel."""
+    def pixel(self, x: int, y: int, color: Optional[bool] = None) -> Optional[bool]:
+        """Get or set the color of a given pixel.
+
+        :param int x: The x coordinate of the pixel
+        :param int y: The y coordinate of the pixel
+        :param bool color: (Optional) The state to set the pixel
+        :return: If ``color`` was not set, this returns the state of the pixel
+        :rtype: bool
+        """
         if not 0 <= x <= 7:
             return None
         if not 0 <= y <= 7:
@@ -201,8 +237,12 @@ def pixel(self, x, y, color=None):
             return super()._pixel(y, x) | super()._pixel(y + 8, x) << 1
         return None
 
-    def fill(self, color):
-        """Fill the whole display with the given color."""
+    def fill(self, color: bool) -> None:
+        """Fill the whole display with the given color.
+
+        :param bool color: Whether to fill the display
+        """
+
         fill1 = 0xFF if color & 0x01 else 0x00
         fill2 = 0xFF if color & 0x02 else 0x00
         for i in range(8):
@@ -211,9 +251,13 @@ def fill(self, color):
         if self._auto_write:
             self.show()
 
-    def image(self, img: Image):
+    def image(self, img: Image) -> None:
         """Set buffer to value of Python Imaging Library image.  The image should
-        be a size equal to the display size."""
+        be a size equal to the display size.
+
+        :param Image img: The image to show
+        """
+
         imwidth, imheight = img.size
         if imwidth != self.columns or imheight != self.rows:
             raise ValueError(