wasp: Even more docstrings

7 files changed, 72 insertions, 19 deletions

diff --git a/wasp/apps/clock.py b/wasp/apps/clock.py
index 4236d9a..f09f2d4 100644
--- a/wasp/apps/clock.py
+++ b/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
diff --git a/wasp/apps/flashlight.py b/wasp/apps/flashlight.py
index c4702a0..5ca9734 100644
--- a/wasp/apps/flashlight.py
+++ b/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.
-
-    Shows a pure white screen with the backlight set to maximum.
-    """
+    """Trivial flashlight application."""
     NAME = 'Torch'
     ICON = icons.torch
 
diff --git a/wasp/apps/launcher.py b/wasp/apps/launcher.py
index 305cc2e..6a8bab7 100644
--- a/wasp/apps/launcher.py
+++ b/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
 
diff --git a/wasp/apps/pager.py b/wasp/apps/pager.py
index 7da8f5a..18322d2 100644
--- a/wasp/apps/pager.py
+++ b/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.
-
-    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.
-    """
+    """Show a long text message in a pager."""
     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))
diff --git a/wasp/apps/testapp.py b/wasp/apps/testapp.py
index 4b64d31..6681aa5 100644
--- a/wasp/apps/testapp.py
+++ b/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
diff --git a/wasp/wasp.py b/wasp/wasp.py
index a92ceed..f8648e4 100644
--- a/wasp/wasp.py
+++ b/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
-   can use this instance to access system services.
+    wasp.system is the system-wide singleton instance of :py:class:`.Manager`.
+    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
diff --git a/wasp/widgets.py b/wasp/widgets.py
index 9aa39a0..9271fe6 100644
--- a/wasp/widgets.py
+++ b/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)