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

3 files changed, 17 insertions, 12 deletions

diff --git a/shared-bindings/analogio/AnalogIn.c b/shared-bindings/analogio/AnalogIn.c
index f07302250..23b08470f 100644
--- a/shared-bindings/analogio/AnalogIn.c
+++ b/shared-bindings/analogio/AnalogIn.c
@@ -45,8 +45,8 @@
 //|    import analogio
 //|    from board import *
 //|
-//|    with analogio.AnalogIn(A1) as adc:
-//|      val = adc.value
+//|    adc = analogio.AnalogIn(A1)
+//|    val = adc.value
 //|
 
 //| .. class:: AnalogIn(pin)
@@ -93,7 +93,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(analogio_analogin_deinit_obj, analogio_analogin_deinit
 
 //|   .. 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 analogio_analogin___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c
index 6b02f8c0a..6b65878b4 100644
--- a/shared-bindings/analogio/AnalogOut.c
+++ b/shared-bindings/analogio/AnalogOut.c
@@ -45,8 +45,8 @@
 //|     import analogio
 //|     from microcontroller import pin
 //|
-//|     with analogio.AnalogOut(pin.PA02) as dac:     # output on pin PA02
-//|       dac.value = 32768                           # makes PA02 1.65V
+//|     dac = analogio.AnalogOut(pin.PA02)          # output on pin PA02
+//|     dac.value = 32768                           # makes PA02 1.65V
 //|
 
 //| .. class:: AnalogOut(pin)
@@ -91,7 +91,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(analogio_analogout_deinit_obj, analogio_analogo
 
 //|   .. 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 analogio_analogout___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/analogio/__init__.c b/shared-bindings/analogio/__init__.c
index 39d6bdcda..b468bcde0 100644
--- a/shared-bindings/analogio/__init__.c
+++ b/shared-bindings/analogio/__init__.c
@@ -53,21 +53,24 @@
 //|     AnalogIn
 //|     AnalogOut
 //|
-//| 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 analogio
 //|   from board import *
 //|
-//|   with analogio.AnalogIn(A0) as pin:
-//|     print(pin.value)
+//|   pin = analogio.AnalogIn(A0)
+//|   print(pin.value)
+//|   pin.deinit()
 //|
 //| This example will initialize the the device, read
 //| :py:data:`~analogio.AnalogIn.value` and then
-//| :py:meth:`~analogio.AnalogIn.deinit` the hardware.
+//| :py:meth:`~analogio.AnalogIn.deinit` the hardware. The last step is optional
+//| because CircuitPython will do it automatically after the program finishes.
 //|
 
 STATIC const mp_rom_map_elem_t analogio_module_globals_table[] = {