Various tidy ups and creation of comments / docs.

Author: ntoll

.gitignore

@@ -12,3 +12,4 @@ dist
 **/*.egg-info
 .vscode
 .coverage
+*.swp

README.rst

@@ -16,9 +16,9 @@ Introduction
 This library provides simple byte and string based inter-device communication
 via BLE.
 
-It works like a walkie-talkie: you can configure your device to a certain
-channel (numbered 0-255, default being 7) and your device will broadcast on
-that channel and receive any messages from other devices using that channel.
+It works like a walkie-talkie: configure your device to use a certain channel
+(numbered 0-255, default being 42) and it will broadcast on that channel and
+receive any messages from other devices using that channel.
 
 Dependencies
 =============

adafruit_radio.py

@@ -28,9 +28,6 @@
 
 * Author(s): Nicholas H.Tollervey for Adafruit Industries
 
-Implementation Notes
---------------------
-
 **Hardware:**
 
    Adafruit Feather nRF52840 Express <https://www.adafruit.com/product/4062>

docs/conf.py

@@ -20,7 +20,7 @@
 # Uncomment the below if you use native CircuitPython modules such as
 # digitalio, micropython and busio. List the modules you use. Without it, the
 # autodoc module docs will fail to generate with a warning.
-# autodoc_mock_imports = ["digitalio", "busio"]
+autodoc_mock_imports = ["digitalio", "busio", "adafruit_ble"]
 
 
 intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}

docs/index.rst

@@ -23,15 +23,9 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
-.. todo:: Add any Learn guide links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
-
 .. toctree::
     :caption: Related Products
 
-.. todo:: Add any product links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
-
 .. toctree::
     :caption: Other Links
 

tests/conftest.py

@@ -1,8 +1,20 @@
+"""
+This file ensures everything is in place to run PyTest based unit tests against
+the adafruit_radio module. It works by using Python's mock library to add
+MagicMock objects to sys.modules for the modules which are not available to
+standard Python because they're CircuitPython only modules.
+
+Such mocking happens as soon as this conftest.py file is imported (so the
+mocked modules exist in sys.modules before the module to be tested is
+imported), and immediately before each test function is evaluated (so changes
+to state remain isolated between tests).
+"""
 import sys
 from unittest.mock import MagicMock
 
-
-# Could this be taken from a configuration setting..?
+# Add fully qualified namespace paths to things that are imported, but which
+# should be mocked away. For instance, modules which are available in
+# CircuitPython but not standard Python.
 MOCK_MODULES = [
     "adafruit_ble.BLERadio",
     "adafruit_ble.advertising.adafruit.AdafruitRadio",
@@ -11,7 +23,8 @@
 
 def mock_imported_modules():
     """
-    Mocks away the modules named in MOCK_MODULES.
+    Mocks away the modules named in MOCK_MODULES, so the module under test
+    can be imported with modules which may not be available.
     """
     module_paths = set()
     for m in MOCK_MODULES:
@@ -26,11 +39,13 @@ def mock_imported_modules():
 
 def pytest_runtest_setup(item):
     """
+    Called immediately before any test function is called.
+
     Recreates afresh the mocked away modules so state between tests remains
     isolated.
     """
     mock_imported_modules()
 
 
-# Needed to stop ImportError when importing module under test.
+# Initial mocking needed to stop ImportError when importing module under test.
 mock_imported_modules()