update docs

belay/__init__.py

@@ -5,6 +5,7 @@
     "minify",
     "Device",
     "SpecialFilenameError",
+    "SpecialFunctionNameError",
     "PyboardException",
 ]
 from ._minify import minify

belay/device.py

@@ -82,11 +82,18 @@ def enumerate_fs(path=""):
 
 
 class SpecialFilenameError(Exception):
-    """Not allowed filename like ``boot.py`` or ``main.py``."""
+    """Reserved filename like ``boot.py`` or ``main.py`` that may impact Belay functionality."""
 
 
 class SpecialFunctionNameError(Exception):
-    """Not allowed function name."""
+    """Reserved function name that may impact Belay functionality.
+
+    Currently limited to:
+
+        * Names that start and end with double underscore, ``__``.
+
+        * Names that start with ``_belay`` or ``__belay``
+    """
 
 
 def local_hash_file(fn):
@@ -106,7 +113,11 @@ def __init__(self, device):
         object.__setattr__(self, "_belay_device", device)
 
     def __setattr__(self, name: str, value: Callable):
-        if name.startswith("_belay") or (name.startswith("__") and name.endswith("__")):
+        if (
+            name.startswith("_belay")
+            or name.startswith("__belay")
+            or (name.startswith("__") and name.endswith("__"))
+        ):
             raise SpecialFunctionNameError(
                 f'Not allowed to register function named "{name}".'
             )

docs/source/How Belay Works.rst

@@ -107,8 +107,8 @@ and then parses back the response. The complete lifecycle looks like this:
 
 This has a few limitations, namely:
 
-1. Each passed in argument must be completely reconstructable by their printable representation. This is true for python literals like numbers, strings, lists, dicts, and sets.
+1. Each passed in argument must be a python literals (``None``, booleans, bytes, numbers, strings, sets, lists, and dicts).
 
-2. The invoked function cannot be printing to stdout, otherwise the host-side parsing of the result won't work.
+2. The invoked code cannot ``print``. Belay uses stdout for data transfer and spurious prints will corrupt the data sent to host.
 
-3. The returned data of the function must be a python literal(s).
+3. The returned data of the function must also be a python literal(s).

examples/03_read_adc/README.rst

@@ -7,4 +7,4 @@ To do this, we explore a new concept: functions can return a value.
 Return values are serialized on-device and deserialized on-host by Belay.
 This is seamless to the user; the function ``read_temperature`` returns a float on-device, and that same float is returned on the host.
 
-Due to how Belay serializes and deserializes data, only python literals (`None`, booleans, bytes, numbers, strings, sets, lists, and dicts) can be returned.
+Due to how Belay serializes and deserializes data, only python literals (``None``, booleans, bytes, numbers, strings, sets, lists, and dicts) can be returned.