DM: update docstrings

deanm1278 · deanm1278 · commit ece830385dcc · 2018-07-16T17:19:49.000-04:00
diff --git a/adafruit_epd/epd.py b/adafruit_epd/epd.py
@@ -1,3 +1,31 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2018 Dean Miller for Adafruit Industries
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_epd.epd` - Adafruit EPD - ePaper display driver
+====================================================================================
+CircuitPython driver for Adafruit ePaper display breakouts
+* Author(s): Dean Miller
+"""
+
 import time
 from adafruit_epd import mcp_sram
 import digitalio
@@ -39,6 +67,7 @@ def __init__(self, width, height, rst_pin, dc_pin, busy_pin, srcs_pin, cs_pin, s
         # pylint: enable=too-many-arguments
 
     def begin(self, reset=True):
+        """Begin display and reset if desired."""
         self._cs.value = True
         self._dc.value = False
 
diff --git a/adafruit_epd/il0373.py b/adafruit_epd/il0373.py
@@ -1,3 +1,31 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2018 Dean Miller for Adafruit Industries
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_epd.il0373` - Adafruit il0373 - ePaper display driver
+====================================================================================
+CircuitPython driver for Adafruit il0373 display breakouts
+* Author(s): Dean Miller
+"""
+
 import time
 from micropython import const
 from adafruit_epd.epd import Adafruit_EPD
@@ -29,6 +57,7 @@
 IL0373_VCM_DC_SETTING = const(0x82)
 
 class Adafruit_IL0373(Adafruit_EPD):
+    """driver class for Adafruit IL0373 ePaper display breakouts"""
     # pylint: disable=too-many-arguments
     def __init__(self, width, height, rst_pin, dc_pin, busy_pin, srcs_pin, cs_pin, spi):
         super(Adafruit_IL0373, self).__init__(width, height, rst_pin, dc_pin, busy_pin,
@@ -41,6 +70,7 @@ def __init__(self, width, height, rst_pin, dc_pin, busy_pin, srcs_pin, cs_pin, s
         # pylint: enable=too-many-arguments
 
     def begin(self, reset=True):
+        """Begin communication with the display and set basic settings"""
         super(Adafruit_IL0373, self).begin(reset)
 
         while self._busy.value is False:
@@ -50,6 +80,7 @@ def begin(self, reset=True):
         self.command(IL0373_BOOSTER_SOFT_START, bytearray([0x17, 0x17, 0x17]))
 
     def update(self):
+        """update the display"""
         self.command(IL0373_DISPLAY_REFRESH)
 
         while self._busy.value is False:
@@ -61,6 +92,7 @@ def update(self):
         time.sleep(2)
 
     def power_up(self):
+        """power up the display"""
         self.command(IL0373_POWER_ON)
 
         while self._busy.value is False:
@@ -80,6 +112,7 @@ def power_up(self):
 
 
     def display(self):
+        """show the contents of the display buffer"""
         self.power_up()
 
         while not self.spi_device.try_lock():
@@ -134,6 +167,7 @@ def display(self):
         self.update()
 
     def draw_pixel(self, x, y, color):
+        """draw a single pixel in the display buffer"""
         if (x < 0) or (x >= self.width) or (y < 0) or (y >= self.height):
             return
 
@@ -156,9 +190,11 @@ def draw_pixel(self, x, y, color):
         return
 
     def clear_buffer(self):
+        """clear the display buffer"""
         self.sram.erase(0x00, self.bw_bufsize, 0xFF)
         self.sram.erase(self.bw_bufsize, self.red_bufsize, 0xFF)
 
     def clear_display(self):
+        """clear the entire display"""
         self.clear_buffer()
         self.display()
diff --git a/adafruit_epd/mcp_sram.py b/adafruit_epd/mcp_sram.py
@@ -1,10 +1,39 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2018 Dean Miller for Adafruit Industries
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_epd.mcp_sram` - Adafruit MCP SRAM - sram driver
+====================================================================================
+CircuitPython driver for Microchip SRAM chips
+* Author(s): Dean Miller
+"""
+
 from micropython import const
 import digitalio
 
 SRAM_SEQUENTIAL_MODE = const(1 << 6)
 
 class Adafruit_MCP_SRAM(object):
-
+    """supporting class for communicating with
+    Microchip SRAM chips"""
     SRAM_READ = 0x03
     SRAM_WRITE = 0x02
     SRAM_RDSR = 0x05
@@ -24,6 +53,7 @@ def __init__(self, cs_pin, spi):
         self.spi_device.unlock()
 
     def write(self, addr, buf, reg=SRAM_WRITE):
+        """write the passed buffer to the passed address"""
         cmd = bytearray([reg, (addr >> 8) & 0xFF, addr & 0xFF] + buf)
 
         while not self.spi_device.try_lock():
@@ -34,6 +64,7 @@ def write(self, addr, buf, reg=SRAM_WRITE):
         self.spi_device.unlock()
 
     def read(self, addr, length, reg=SRAM_READ):
+        """read passed number of bytes at the passed address"""
         cmd = bytearray([reg, (addr >> 8) & 0xFF, addr & 0xFF])
 
         buf = bytearray(length)
@@ -47,19 +78,24 @@ def read(self, addr, length, reg=SRAM_READ):
         return buf
 
     def read8(self, addr, reg=SRAM_READ):
+        """read a single byte at the passed address"""
         return self.read(addr, 1, reg)[0]
 
     def read16(self, addr, reg=SRAM_READ):
+        """read 2 bytes at the passed address"""
         buf = self.read(addr, 2, reg)
         return buf[0] << 8 | buf[1]
 
     def write8(self, addr, value, reg=SRAM_WRITE):
+        """write a single byte at the passed address"""
         self.write(addr, [value], reg)
 
     def write16(self, addr, value, reg=SRAM_WRITE):
+        """write 2 bytes at the passed address"""
         self.write(addr, [value >> 8, value], reg)
 
     def erase(self, addr, length, value):
+        """erase the passed number of bytes starting at the passed address"""
         cmd = bytearray([Adafruit_MCP_SRAM.SRAM_WRITE, (addr >> 8) & 0xFF, addr & 0xFF])
 
         while not self.spi_device.try_lock():
