wasp: Even more docstrings

docs/wasp.rst

@@ -6,35 +6,32 @@ WASP Reference Manual
 .. contents::
     :local:
 
-System management
+System
------------------
+------
 
 .. automodule:: wasp
    :members:
-   :undoc-members:
 
-Applications
+.. automodule:: draw565
-------------
+   :members:
 
-.. automodule:: apps.clock
+.. automodule:: icons
    :members:
    :undoc-members:
 
-.. automodule:: apps.flashlight
+.. automodule:: fonts.clock
    :members:
    :undoc-members:
 
-.. automodule:: apps.launcher
+.. automodule:: fonts.sans24
+   :members:
+
+.. automodule:: logo
    :members:
    :undoc-members:
 
-.. automodule:: apps.pager
+.. automodule:: widgets
    :members:
-   :undoc-members:
-
-.. automodule:: apps.testapp
-   :members:
-   :undoc-members:
 
 Device drivers
 --------------
@@ -57,28 +54,26 @@ Device drivers
 .. automodule:: drivers.vibrator
    :members:
 
-Libraries
+Applications
----------
+------------
 
-.. automodule:: draw565
+.. automodule:: apps.clock
-   :members:
-
-.. automodule:: icons
    :members:
    :undoc-members:
 
-.. automodule:: fonts.clock
+.. automodule:: apps.flashlight
    :members:
    :undoc-members:
 
-.. automodule:: fonts.sans24
+.. automodule:: apps.launcher
-   :members:
-
-.. automodule:: logo
    :members:
    :undoc-members:
 
-.. automodule:: widgets
+.. automodule:: apps.pager
+   :members:
+   :undoc-members:
+
+.. automodule:: apps.testapp
    :members:
    :undoc-members:
 
@@ -139,8 +134,8 @@ active (during splash screen or early UART recovery mode, during an
 update). It can be consumed by the application to prevent the current
 time being lost during an update.
 
-Watchdog
+Watchdog protocol
---------
+~~~~~~~~~~~~~~~~~
 
 Form-factor devices such as smart watches and fitness trackers do not usually
 have any hardware mechanism to allow the user to force a failed device into
@@ -156,9 +151,6 @@ The software responsibilities to implement this are split between the
 bootloader and the application, although the application responsibilities
 are intentionally minimal.
 
-Bootloader
-~~~~~~~~~~
-
 The bootloader implements an over-the-air recovery mode, as well as handling
 normal boot, where it's role is to display the splash screen.
 
@@ -183,14 +175,9 @@ From this list #1 and #2 are needed to ensure robust WDT handling whilst #3
 and # 4 ensure the user can switch back to application from the device
 itself if they ever accidentally trigger entry to recovery mode.
 
-Application
-~~~~~~~~~~~
-
 The application's role is to carefully pet the watchdog so that it will
 trigger automatically if the hardware button is held down for five
-seconds.
+seconds. Key points for application robustness include:
-
-Key points for robustness:
 
 1. Unlike a normal watchdog we can be fairly reckless about where in the
    code we pet the dog. For example petting the dog from a timer interrupt

wasp/apps/clock.py

@@ -1,6 +1,12 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) 2020 Daniel Thompson
 
+"""Digital clock
+~~~~~~~~~~~~~~~~
+
+Shows a time (as HH:MM) together with a battery meter and the date.
+"""
+
 import wasp
 
 import icons
@@ -23,8 +29,6 @@ MONTH = 'JanFebMarAprMayJunJulAugSepOctNovDec'
 
 class ClockApp():
     """Simple digital clock application.
-
-    Shows a time (as HH:MM) together with a battery meter and the date.
     """
     NAME = 'Clock'
     ICON = icons.clock

wasp/apps/flashlight.py

@@ -1,15 +1,18 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) 2020 Daniel Thompson
 
+"""Flashlight
+~~~~~~~~~~~~~
+
+Shows a pure white screen with the backlight set to maximum.
+"""
+
 import wasp
 
 import icons
 
 class FlashlightApp(object):
-    """Trivial flashlight application.
+    """Trivial flashlight application."""
-
-    Shows a pure white screen with the backlight set to maximum.
-    """
     NAME = 'Torch'
     ICON = icons.torch
 

wasp/apps/launcher.py

@@ -1,6 +1,10 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) 2020 Daniel Thompson
 
+"""Application launcher
+~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
 import wasp
 import icons
 

wasp/apps/pager.py

@@ -1,20 +1,22 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) 2020 Daniel Thompson
 
+"""Pager applications
+~~~~~~~~~~~~~~~~~~~~~
+
+The pager is used to present text based information to the user. It is
+primarily intended for notifications but is also used to provide debugging
+information when applications crash.
+"""
+
 import wasp
 import icons
 
 import io
 import sys
 
-
 class PagerApp():
-    """Show long text in a pager.
+    """Show a long text message in a pager."""
-
-    This is used to present text based information to the user. It is primarily
-    intended for notifications but is also used to provide debugging
-    information when applications crash.
-    """
     NAME = 'Pager'
     ICON = icons.app
 
@@ -31,10 +33,12 @@ class PagerApp():
         self._draw()
 
     def background(self):
+        """De-activate the application."""
         del self._chunks
         del self._numpages
 
     def swipe(self, event):
+        """Swipe to page up/down."""
         mute = wasp.watch.display.mute
 
         if event[0] == wasp.EventType.UP:
@@ -114,6 +118,5 @@ class CrashApp():
         wasp.watch.display.invert(True)
 
     def swipe(self, event):
-        """Show the exception message in a pager.
+        """Show the exception message in a pager."""
-        """
         wasp.system.switch(PagerApp(self._msg))

wasp/apps/testapp.py

@@ -1,6 +1,10 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) 2020 Daniel Thompson
 
+"""Self Tests
+~~~~~~~~~~~~~
+"""
+
 import machine
 import wasp
 import icons

wasp/wasp.py

@@ -1,11 +1,18 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) 2020 Daniel Thompson
-"""WASP system management (including constants)
+"""Wasp-os system manager
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. data:: system = Manager()
+.. data:: wasp.system
 
-   system is the system-wide instance of the Manager class. Applications
+    wasp.system is the system-wide singleton instance of :py:class:`.Manager`.
-   can use this instance to access system services.
+    Application must use this instance to access the system services provided
+    by the manager.
+
+.. data:: wasp.watch
+
+    wasp.watch is an import of :py:mod:`watch` and is simply provided as a
+    shortcut (and to reduce memory by keeping it out of other namespaces).
 """
 
 import gc

wasp/widgets.py

@@ -1,18 +1,35 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) 2020 Daniel Thompson
 
+"""Widget library
+~~~~~~~~~~~~~~~~~
+
+The widget library allows common fragments of logic and drawing code to be
+shared between applications.
+"""
+
 import icons
 import watch
 
 class BatteryMeter(object):
+    """Battery meter widget.
+
+    A simple battery meter with a charging indicator, will draw at the
+    top-right of the display.
+    """
     def __init__(self):
         self.level = -2
 
     def draw(self):
+        """Draw from meter (from scratch)."""
         self.level = -2
         self.update()
 
     def update(self):
+        """Update the meter.
+
+        The update is lazy and won't redraw unless the level has changed.
+        """
         icon = icons.battery
         draw = watch.drawable
 
@@ -52,15 +69,26 @@ class BatteryMeter(object):
             self.level = level
 
 class ScrollIndicator():
+    """Scrolling indicator.
+
+    A simple battery meter with a charging indicator, will draw at the
+    top-right of the display.
+    """
     def __init__(self, x=240-18, y=240-24):
         self._pos = (x, y)
         self.up = True
         self.down = True
 
     def draw(self):
+        """Draw from scrolling indicator.
+
+        For this simple widget :py:meth:`~.draw` is simply a synonym for
+        :py:meth:`~.update`.
+        """
         self.update()
 
     def update(self):
+        """Update from scrolling indicator."""
         draw = watch.drawable
         if self.up:
             draw.rleblit(icons.up_arrow, pos=self._pos, fg=0x7bef)