improve demo script description

Author: anton-ptashnik

godice/demo.py

@@ -19,6 +19,9 @@ async def main():
     dev, _adv_data = select_closest_device(dev_advdata_tuples)
     client = bleak.BleakClient(dev, timeout=15)
 
+    # Python context manager (async with) is used for convenient connection handling
+    # Device stays connected during `async with` block execution and auto-disconnected on block finish
+    # Otherwise, dice.connect/dice.disconnect can be used instead 
     async with godice.create(client, godice.DiceShell.D6) as dice:
         print(f"Connected to {dev.name}")
 
@@ -33,16 +36,25 @@ async def main():
         print(f"Battery: {battery_lvl}")
 
         print("Listening to position updates. Flip your dice")
-        await dice.subscribe_number_notification(print_notification)
+        await dice.subscribe_number_notification(notification_callback)
         await asyncio.sleep(30)
         await dice.set_led(off_rgb, off_rgb)
 
 
-async def print_notification(number, stability_descr):
+async def notification_callback(number, stability_descr):
+    """
+    GoDice number notification callback.
+    Called each time GoDice is flipped, receiving flip event data:
+    :param number: a rolled number
+    :param stability_descr: an additional value clarifying device movement state, ie stable, rolling...
+    """
     print(f"Number: {number}, stability descriptor: {stability_descr}")
 
 
 def filter_godice_devices(dev_advdata_tuples):
+    """
+    Receives all discovered devices and returns only GoDice devices
+    """
     return [
         (dev, adv_data)
         for dev, adv_data in dev_advdata_tuples
@@ -51,6 +63,9 @@ def filter_godice_devices(dev_advdata_tuples):
 
 
 def select_closest_device(dev_advdata_tuples):
+    """
+    Finds the closest device based on RSSI are returns it
+    """
     def _rssi_as_key(dev_advdata):
         _, adv_data = dev_advdata
         return adv_data.rssi
@@ -59,9 +74,14 @@ def _rssi_as_key(dev_advdata):
 
 
 def print_device_info(devices):
+    """
+    Prints short summary of discovered devices
+    """
     for dev, adv_data in devices:
         print(f"Name: {dev.name}, address: {dev.address}, rssi: {adv_data.rssi}")
 
 
+# identify if the script is called directly and run if so
+# asyncio.run starts execution in Python async environment
 if __name__ == "__main__":
     asyncio.run(main())