shared-bindings: Update docs to remove with statements from examples but add more detail to the design guide about their use.

2 files changed, 14 insertions, 12 deletions

diff --git a/shared-bindings/touchio/TouchIn.c b/shared-bindings/touchio/TouchIn.c
index f4e82994c..894781423 100644
--- a/shared-bindings/touchio/TouchIn.c
+++ b/shared-bindings/touchio/TouchIn.c
@@ -45,9 +45,10 @@
 //|    import touchio
 //|    from board import *
 //|
-//|    with touchio.TouchIn(A1) as touch:
-//|      if touch.value:
-//|        print("touched!")
+//|    touch = touchio.TouchIn(A1)
+//|    while True:
+//|        if touch.value:
+//|            print("touched!")
 //|
 
 //| .. class:: TouchIn(pin)
@@ -92,7 +93,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(touchio_touchin_deinit_obj, touchio_touchin_dei
 
 //|   .. method:: __exit__()
 //|
-//|      Automatically deinitializes the hardware when exiting a context.
+//|      Automatically deinitializes the hardware when exiting a context. See
+//|      :ref:`lifetime-and-contextmanagers` for more info.
 //|
 STATIC mp_obj_t touchio_touchin_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/touchio/__init__.c b/shared-bindings/touchio/__init__.c
index a930c1af7..6adbe09cf 100644
--- a/shared-bindings/touchio/__init__.c
+++ b/shared-bindings/touchio/__init__.c
@@ -52,21 +52,21 @@
 //|
 //|     TouchIn
 //|
-//| All libraries change hardware state and should be deinitialized when they
-//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a
-//| context manager.
+//| All classes change hardware state and should be deinitialized when they
+//| are no longer needed if the program continues after use. To do so, either
+//| call :py:meth:`!deinit` or use a context manager. See
+//| :ref:`lifetime-and-contextmanagers` for more info.
 //|
 //| For example::
 //|
 //|   import touchio
 //|   from board import *
 //|
-//|   with touchio.TouchIn(D6) as touch_pin:
-//|     print(touch_pin.value)
+//|   touch_pin = touchio.TouchIn(D6)
+//|   print(touch_pin.value)
 //|
-//| This example will initialize the the device, run
-//| :py:data:`~touchio.TouchIn.value` and then :py:meth:`~touchio.TouchIn.deinit`
-//| the hardware.
+//| This example will initialize the the device, and print the
+//| :py:data:`~touchio.TouchIn.value`.
 //|
 
 STATIC const mp_rom_map_elem_t touchio_module_globals_table[] = {