add docstring

Author: xiongyihui

keyboard/__init__.py

@@ -69,6 +69,7 @@
 
 @micropython.asm_thumb
 def mem(r0):
+    """Read memory from the address"""
     ldr(r0, [r0, 0])
 
 
@@ -82,6 +83,7 @@ def reset_into_bootloader():
 
 
 def is_tapped(matrix, key):
+    """Check if the key is tapped (press & release quickly)"""
     n = len(matrix)
     if n == 0:
         n = matrix.wait(500 - matrix.ms(matrix.time() - matrix.get_keydown_time(key)))
@@ -94,6 +96,7 @@ def is_tapped(matrix, key):
                 200 - matrix.ms(matrix.time() - matrix.get_keydown_time(key))
             )
     if n == 2 and target == matrix.view(1):
+        # Fast typing: A down, B down, A up, B up
         return True
 
     return False

keyboard/matrix.py

@@ -5,10 +5,16 @@
 
 
 class Matrix:
+    """
+    Implement the drive of keyboard matrix and provide an event queue.
+    """
+
     # ROWS = (P0_05, P0_06, P0_07, P0_08, P1_09, P1_08, P0_12, P0_11)
     # COLS = (P0_19, P0_20, P0_21, P0_22, P0_23, P0_24, P0_25, P0_26)
     ROWS = ()
     COLS = ()
+
+    # direction of diode
     ROW2COL = False
 
     def __init__(self):
@@ -42,6 +48,11 @@ def __init__(self):
         self._debounce_time = 20000000
 
     def scan(self):
+        """
+        Scan keyboard matrix and save key event into the queue.
+
+        :return: length of the key event queue.
+        """
         t = time.monotonic_ns()
 
         # use local variables to speed up
@@ -83,7 +94,8 @@ def scan(self):
 
         return self.length
 
-    def wait(self, timeout=0):
+    def wait(self, timeout=1000):
+        """Wait for a new key event or timeout"""
         last = self.length
         if timeout:
             end_time = time.monotonic_ns() + timeout * 1000000
@@ -98,13 +110,15 @@ def wait(self, timeout=0):
                     return n
 
     def put(self, data):
+        """Put a key event into the queue"""
         self.queue[self.head] = data
         self.head += 1
         if self.head >= self.keys:
             self.head = 0
         self.length += 1
 
     def get(self):
+        """Remove and return the first event from the queue."""
         data = self.queue[self.tail]
         self.tail += 1
         if self.tail >= self.keys:
@@ -113,24 +127,31 @@ def get(self):
         return data
 
     def view(self, n):
+        """Return the specified event"""
         return self.queue[(self.tail + n) % self.keys]
 
     def __getitem__(self, n):
+        """Return the specified event"""
         return self.queue[(self.tail + n) % self.keys]
 
     def __len__(self):
+        """Return the number of events in the queue"""
         return self.length
 
     def get_keydown_time(self, key):
+        """Return the key pressed time"""
         return self.t0[key]
 
     def get_keyup_time(self, key):
+        """Return the key released time"""
         return self.t1[key]
 
     def time(self):
+        """Return current time"""
         return time.monotonic_ns()
 
     def ms(self, t):
+        """Convert time to milliseconds"""
         return t // 1000000
 
     @property
@@ -139,7 +160,9 @@ def debounce_time(self):
 
     @debounce_time.setter
     def debounce_time(self, t):
+        """Set debounce time"""
         self._debounce_time = t * 1000000
 
     def suspend(self):
+        """Suspend keyboard"""
         pass