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

4 files changed, 20 insertions, 14 deletions

diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c
index 6c2c4223f..147a8d4f1 100644
--- a/shared-bindings/bitbangio/I2C.c
+++ b/shared-bindings/bitbangio/I2C.c
@@ -90,7 +90,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_deinit_obj, bitbangio_i2c_obj_deinit);
 
 //|   .. method:: I2C.__exit__()
 //|
-//|     Automatically deinitializes the hardware on context exit.
+//|     Automatically deinitializes the hardware on context exit. See
+//|     :ref:`lifetime-and-contextmanagers` for more info.
 //|
 STATIC mp_obj_t bitbangio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/bitbangio/OneWire.c b/shared-bindings/bitbangio/OneWire.c
index 14645444d..bbdf7c8f5 100644
--- a/shared-bindings/bitbangio/OneWire.c
+++ b/shared-bindings/bitbangio/OneWire.c
@@ -55,11 +55,11 @@
 //|     import bitbangio
 //|     import board
 //|
-//|     with bitbangio.OneWire(board.D7) as onewire:
-//|       onewire.reset()
-//|       onewire.write_bit(True)
-//|       onewire.write_bit(False)
-//|       print(onewire.read_bit())
+//|     onewire = bitbangio.OneWire(board.D7)
+//|     onewire.reset()
+//|     onewire.write_bit(True)
+//|     onewire.write_bit(False)
+//|     print(onewire.read_bit())
 //|
 STATIC mp_obj_t bitbangio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) {
     mp_arg_check_num(n_args, n_kw, 1, MP_OBJ_FUN_ARGS_MAX, true);
@@ -101,7 +101,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_onewire_deinit_obj, bitbangio_onewire
 
 //|   .. 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 bitbangio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c
index f8cf90628..8589025d9 100644
--- a/shared-bindings/bitbangio/SPI.c
+++ b/shared-bindings/bitbangio/SPI.c
@@ -102,7 +102,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_deinit_obj, bitbangio_spi_obj_deinit);
 
 //|   .. method:: SPI.__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 bitbangio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/bitbangio/__init__.c b/shared-bindings/bitbangio/__init__.c
index 85acab0d3..3123fb199 100644
--- a/shared-bindings/bitbangio/__init__.c
+++ b/shared-bindings/bitbangio/__init__.c
@@ -64,21 +64,24 @@
 //|     OneWire
 //|     SPI
 //|
-//| 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 bitbangio
 //|   from board import *
 //|
-//|   with bitbangio.I2C(SCL, SDA) as i2c:
-//|     i2c.scan()
+//|   i2c = bitbangio.I2C(SCL, SDA)
+//|   print(i2c.scan())
+//|   i2c.deinit()
 //|
 //| This example will initialize the the device, run
 //| :py:meth:`~bitbangio.I2C.scan` and then :py:meth:`~bitbangio.I2C.deinit` the
-//| hardware.
+//| hardware. The last step is optional because CircuitPython automatically
+//| resets hardware after a program finishes.
 //|
 
 STATIC const mp_rom_map_elem_t bitbangio_module_globals_table[] = {