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

26 files changed, 314 insertions, 280 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[] = {
diff --git a/shared-bindings/audioio/AudioOut.c b/shared-bindings/audioio/AudioOut.c
index a765994d5..b47652104 100644
--- a/shared-bindings/audioio/AudioOut.c
+++ b/shared-bindings/audioio/AudioOut.c
@@ -66,10 +66,10 @@
 //|     for i in range(length):
 //|         b[i] = int(math.sin(math.pi * 2 * i / 18) * (2 ** 15) + 2 ** 15)
 //|
-//|     with audioio.AudioOut(board.SPEAKER, sin_wave) as sample:
-//|         sample.play(loop=True)
-//|         time.sleep(1)
-//|         sample.stop()
+//|     sample = audioio.AudioOut(board.SPEAKER, sin_wave)
+//|     sample.play(loop=True)
+//|     time.sleep(1)
+//|     sample.stop()
 //|
 //|   Playing a wave file from flash::
 //|
@@ -136,7 +136,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_deinit_obj, audioio_audioout_d
 
 //|   .. 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 audioio_audioout_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/audioio/__init__.c b/shared-bindings/audioio/__init__.c
index 3e831a171..07305a45a 100644
--- a/shared-bindings/audioio/__init__.c
+++ b/shared-bindings/audioio/__init__.c
@@ -49,9 +49,10 @@
 //|
 //|     AudioOut
 //|
-//| 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.
 //|
 
 STATIC const mp_rom_map_elem_t audioio_module_globals_table[] = {
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[] = {
diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c
index b1794fdfb..a10a792fd 100644
--- a/shared-bindings/busio/I2C.c
+++ b/shared-bindings/busio/I2C.c
@@ -85,9 +85,9 @@ STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, siz
 //|     Releases control of the underlying hardware so other classes can use it.
 //|
 STATIC mp_obj_t busio_i2c_obj_deinit(mp_obj_t self_in) {
-   busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   common_hal_busio_i2c_deinit(self);
-   return mp_const_none;
+    busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    common_hal_busio_i2c_deinit(self);
+    return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_deinit_obj, busio_i2c_obj_deinit);
 
@@ -99,7 +99,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_deinit_obj, busio_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 busio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
@@ -123,17 +124,17 @@ static void check_lock(busio_i2c_obj_t *self) {
 //|      :rtype: list
 //|
 STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) {
-   busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   check_lock(self);
-   mp_obj_t list = mp_obj_new_list(0, NULL);
-   // 7-bit addresses 0b0000xxx and 0b1111xxx are reserved
-   for (int addr = 0x08; addr < 0x78; ++addr) {
-       bool success = common_hal_busio_i2c_probe(self, addr);
-       if (success) {
-           mp_obj_list_append(list, MP_OBJ_NEW_SMALL_INT(addr));
-       }
-   }
-   return list;
+    busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    check_lock(self);
+    mp_obj_t list = mp_obj_new_list(0, NULL);
+    // 7-bit addresses 0b0000xxx and 0b1111xxx are reserved
+    for (int addr = 0x08; addr < 0x78; ++addr) {
+        bool success = common_hal_busio_i2c_probe(self, addr);
+        if (success) {
+            mp_obj_list_append(list, MP_OBJ_NEW_SMALL_INT(addr));
+        }
+    }
+    return list;
 }
 MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan);
 
diff --git a/shared-bindings/busio/OneWire.c b/shared-bindings/busio/OneWire.c
index 52aed2135..f270d9d92 100644
--- a/shared-bindings/busio/OneWire.c
+++ b/shared-bindings/busio/OneWire.c
@@ -55,11 +55,11 @@
 //|     import busio
 //|     import board
 //|
-//|     with busio.OneWire(board.D7) as onewire:
-//|       onewire.reset()
-//|       onewire.write_bit(True)
-//|       onewire.write_bit(False)
-//|       print(onewire.read_bit())
+//|     onewire = busio.OneWire(board.D7)
+//|     onewire.reset()
+//|     onewire.write_bit(True)
+//|     onewire.write_bit(False)
+//|     print(onewire.read_bit())
 //|
 STATIC mp_obj_t busio_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(busio_onewire_deinit_obj, busio_onewire_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 busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c
index 0fb0c7ddf..9f073234e 100644
--- a/shared-bindings/busio/SPI.c
+++ b/shared-bindings/busio/SPI.c
@@ -115,7 +115,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_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 busio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c
index 11ee91355..6b053ad7e 100644
--- a/shared-bindings/busio/UART.c
+++ b/shared-bindings/busio/UART.c
@@ -63,54 +63,54 @@ extern const busio_uart_parity_obj_t busio_uart_parity_even_obj;
 extern const busio_uart_parity_obj_t busio_uart_parity_odd_obj;
 
 STATIC mp_obj_t busio_uart_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, 0, MP_OBJ_FUN_ARGS_MAX, true);
-   busio_uart_obj_t *self = m_new_obj(busio_uart_obj_t);
-   self->base.type = &busio_uart_type;
-   mp_map_t kw_args;
-   mp_map_init_fixed_table(&kw_args, n_kw, pos_args + n_args);
-   enum { ARG_tx, ARG_rx, ARG_baudrate, ARG_bits, ARG_parity, ARG_stop, ARG_timeout, ARG_receiver_buffer_size};
-   static const mp_arg_t allowed_args[] = {
-       { MP_QSTR_tx, MP_ARG_REQUIRED | MP_ARG_OBJ },
-       { MP_QSTR_rx, MP_ARG_REQUIRED | MP_ARG_OBJ },
-       { MP_QSTR_baudrate, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 9600} },
-       { MP_QSTR_bits, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 8} },
-       { MP_QSTR_parity, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = mp_const_none} },
-       { MP_QSTR_stop, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 1} },
-       { MP_QSTR_timeout, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 1000} },
-       { MP_QSTR_receiver_buffer_size, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 64} },
-   };
-   mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
-   mp_arg_parse_all(n_args, pos_args, &kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
-
-   assert_pin(args[ARG_rx].u_obj, true);
-   const mcu_pin_obj_t* rx = MP_OBJ_TO_PTR(args[ARG_rx].u_obj);
-   assert_pin_free(rx);
-
-   assert_pin(args[ARG_tx].u_obj, true);
-   const mcu_pin_obj_t* tx = MP_OBJ_TO_PTR(args[ARG_tx].u_obj);
-   assert_pin_free(tx);
-
-   uint8_t bits = args[ARG_bits].u_int;
-   if (bits < 7 || bits > 9) {
-       mp_raise_ValueError("bits must be 7, 8 or 9");
-   }
-
-   uart_parity_t parity = PARITY_NONE;
-   if (args[ARG_parity].u_obj == &busio_uart_parity_even_obj) {
-       parity = PARITY_EVEN;
-   } else if (args[ARG_parity].u_obj == &busio_uart_parity_odd_obj) {
-       parity = PARITY_ODD;
-   }
-
-   uint8_t stop = args[ARG_stop].u_int;
-   if (stop != 1 && stop != 2) {
-       mp_raise_ValueError("stop must be 1 or 2");
-   }
-
-   common_hal_busio_uart_construct(self, tx, rx,
-       args[ARG_baudrate].u_int, bits, parity, stop, args[ARG_timeout].u_int,
-       args[ARG_receiver_buffer_size].u_int);
-   return (mp_obj_t)self;
+    mp_arg_check_num(n_args, n_kw, 0, MP_OBJ_FUN_ARGS_MAX, true);
+    busio_uart_obj_t *self = m_new_obj(busio_uart_obj_t);
+    self->base.type = &busio_uart_type;
+    mp_map_t kw_args;
+    mp_map_init_fixed_table(&kw_args, n_kw, pos_args + n_args);
+    enum { ARG_tx, ARG_rx, ARG_baudrate, ARG_bits, ARG_parity, ARG_stop, ARG_timeout, ARG_receiver_buffer_size};
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_tx, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_rx, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_baudrate, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 9600} },
+        { MP_QSTR_bits, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 8} },
+        { MP_QSTR_parity, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = mp_const_none} },
+        { MP_QSTR_stop, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 1} },
+        { MP_QSTR_timeout, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 1000} },
+        { MP_QSTR_receiver_buffer_size, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 64} },
+    };
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args, pos_args, &kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    assert_pin(args[ARG_rx].u_obj, true);
+    const mcu_pin_obj_t* rx = MP_OBJ_TO_PTR(args[ARG_rx].u_obj);
+    assert_pin_free(rx);
+
+    assert_pin(args[ARG_tx].u_obj, true);
+    const mcu_pin_obj_t* tx = MP_OBJ_TO_PTR(args[ARG_tx].u_obj);
+    assert_pin_free(tx);
+
+    uint8_t bits = args[ARG_bits].u_int;
+    if (bits < 7 || bits > 9) {
+        mp_raise_ValueError("bits must be 7, 8 or 9");
+    }
+
+    uart_parity_t parity = PARITY_NONE;
+    if (args[ARG_parity].u_obj == &busio_uart_parity_even_obj) {
+        parity = PARITY_EVEN;
+    } else if (args[ARG_parity].u_obj == &busio_uart_parity_odd_obj) {
+        parity = PARITY_ODD;
+    }
+
+    uint8_t stop = args[ARG_stop].u_int;
+    if (stop != 1 && stop != 2) {
+        mp_raise_ValueError("stop must be 1 or 2");
+    }
+
+    common_hal_busio_uart_construct(self, tx, rx,
+        args[ARG_baudrate].u_int, bits, parity, stop, args[ARG_timeout].u_int,
+        args[ARG_receiver_buffer_size].u_int);
+    return (mp_obj_t)self;
 }
 
 //|   .. method:: deinit()
@@ -118,9 +118,9 @@ STATIC mp_obj_t busio_uart_make_new(const mp_obj_type_t *type, size_t n_args, si
 //|      Deinitialises the UART and releases any hardware resources for reuse.
 //|
 STATIC mp_obj_t busio_uart_obj_deinit(mp_obj_t self_in) {
-   busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   common_hal_busio_uart_deinit(self);
-   return mp_const_none;
+    busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    common_hal_busio_uart_deinit(self);
+    return mp_const_none;
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_deinit_obj, busio_uart_obj_deinit);
 
@@ -132,7 +132,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_deinit_obj, busio_uart_obj_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 busio_uart_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/busio/__init__.c b/shared-bindings/busio/__init__.c
index 9e075752d..4686e7287 100644
--- a/shared-bindings/busio/__init__.c
+++ b/shared-bindings/busio/__init__.c
@@ -65,21 +65,24 @@
 //|     SPI
 //|     UART
 //|
-//| 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 busio
 //|   from board import *
 //|
-//|   with busio.I2C(SCL, SDA) as i2c:
-//|     i2c.scan()
+//|   i2c = busio.I2C(SCL, SDA)
+//|   print(i2c.scan())
+//|   i2c.deinit()
 //|
 //| This example will initialize the the device, run
 //| :py:meth:`~busio.I2C.scan` and then :py:meth:`~busio.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 busio_module_globals_table[] = {
diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c
index e5b7c4241..6b85bc6ea 100644
--- a/shared-bindings/digitalio/DigitalInOut.c
+++ b/shared-bindings/digitalio/DigitalInOut.c
@@ -76,9 +76,9 @@ STATIC mp_obj_t digitalio_digitalinout_make_new(const mp_obj_type_t *type,
 //|      Turn off the DigitalInOut and release the pin for other use.
 //|
 STATIC mp_obj_t digitalio_digitalinout_obj_deinit(mp_obj_t self_in) {
-   digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   common_hal_digitalio_digitalinout_deinit(self);
-   return mp_const_none;
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    common_hal_digitalio_digitalinout_deinit(self);
+    return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_deinit_obj, digitalio_digitalinout_obj_deinit);
 
@@ -90,7 +90,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_deinit_obj, digitalio_digitalin
 
 //|   .. 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 digitalio_digitalinout_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
@@ -115,22 +116,22 @@ extern const digitalio_digitalinout_drive_mode_obj_t digitalio_digitalinout_driv
 extern const digitalio_digitalinout_drive_mode_obj_t digitalio_digitalinout_drive_mode_open_drain_obj;
 
 STATIC mp_obj_t digitalio_digitalinout_switch_to_output(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-   enum { ARG_value, ARG_drive_mode };
-   static const mp_arg_t allowed_args[] = {
-       { MP_QSTR_value,      MP_ARG_BOOL, {.u_bool = false} },
-       { MP_QSTR_drive_mode, MP_ARG_OBJ, {.u_rom_obj = &digitalio_digitalinout_drive_mode_push_pull_obj} },
-   };
-   digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
-   mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
-   mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
-
-   enum digitalinout_drive_mode_t drive_mode = DRIVE_MODE_PUSH_PULL;
-   if (args[ARG_drive_mode].u_rom_obj == &digitalio_digitalinout_drive_mode_open_drain_obj) {
-       drive_mode = DRIVE_MODE_OPEN_DRAIN;
-   }
-   // do the transfer
-   common_hal_digitalio_digitalinout_switch_to_output(self, args[ARG_value].u_bool, drive_mode);
-   return mp_const_none;
+    enum { ARG_value, ARG_drive_mode };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_value,      MP_ARG_BOOL, {.u_bool = false} },
+        { MP_QSTR_drive_mode, MP_ARG_OBJ, {.u_rom_obj = &digitalio_digitalinout_drive_mode_push_pull_obj} },
+    };
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    enum digitalinout_drive_mode_t drive_mode = DRIVE_MODE_PUSH_PULL;
+    if (args[ARG_drive_mode].u_rom_obj == &digitalio_digitalinout_drive_mode_open_drain_obj) {
+        drive_mode = DRIVE_MODE_OPEN_DRAIN;
+    }
+    // do the transfer
+    common_hal_digitalio_digitalinout_switch_to_output(self, args[ARG_value].u_bool, drive_mode);
+    return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_output_obj, 1, digitalio_digitalinout_switch_to_output);
 
@@ -145,11 +146,11 @@ MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_output_obj, 1, digit
 //|       import digitalio
 //|       import board
 //|
-//|       with digitalio.DigitalInOut(board.SLIDE_SWITCH) as switch:
-//|         switch.switch_to_input(pull=digitalio.DigitalInOut.Pull.UP)
-//|         # Or, after switch_to_input
-//|         switch.pull = digitalio.DigitalInOut.Pull.UP
-//|         print(switch.value)
+//|       switch = digitalio.DigitalInOut(board.SLIDE_SWITCH)
+//|       switch.switch_to_input(pull=digitalio.DigitalInOut.Pull.UP)
+//|       # Or, after switch_to_input
+//|       switch.pull = digitalio.DigitalInOut.Pull.UP
+//|       print(switch.value)
 //|
 typedef struct {
     mp_obj_base_t base;
@@ -158,34 +159,34 @@ extern const digitalio_digitalinout_pull_obj_t digitalio_digitalinout_pull_up_ob
 extern const digitalio_digitalinout_pull_obj_t digitalio_digitalinout_pull_down_obj;
 
 STATIC mp_obj_t digitalio_digitalinout_switch_to_input(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-   enum { ARG_pull };
-   static const mp_arg_t allowed_args[] = {
-       { MP_QSTR_pull, MP_ARG_OBJ, {.u_rom_obj = mp_const_none} },
-   };
-   digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
-   mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
-   mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
-
-   enum digitalinout_pull_t pull = PULL_NONE;
-   if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_up_obj) {
-       pull = PULL_UP;
-   }else if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_down_obj) {
-       pull = PULL_DOWN;
-   }
-   // do the transfer
-   common_hal_digitalio_digitalinout_switch_to_input(self, pull);
-   return mp_const_none;
+    enum { ARG_pull };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_pull, MP_ARG_OBJ, {.u_rom_obj = mp_const_none} },
+    };
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    enum digitalinout_pull_t pull = PULL_NONE;
+    if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_up_obj) {
+        pull = PULL_UP;
+    }else if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_down_obj) {
+        pull = PULL_DOWN;
+    }
+    // do the transfer
+    common_hal_digitalio_digitalinout_switch_to_input(self, pull);
+    return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_input_obj, 1, digitalio_digitalinout_switch_to_input);
 
 //|   .. attribute:: direction
 //|
-//|       The direction of the pin.
+//|     The direction of the pin.
 //|
-//|       Setting this will use the defaults from the corresponding
-//|       :py:meth:`switch_to_input` or :py:meth:`switch_to_output` method. If
-//|       you want to set pull, value or drive mode prior to switching, then use
-//|       those methods instead.
+//|     Setting this will use the defaults from the corresponding
+//|     :py:meth:`switch_to_input` or :py:meth:`switch_to_output` method. If
+//|     you want to set pull, value or drive mode prior to switching, then use
+//|     those methods instead.
 //|
 typedef struct {
     mp_obj_base_t base;
@@ -194,12 +195,12 @@ extern const digitalio_digitalinout_direction_obj_t digitalio_digitalinout_direc
 extern const digitalio_digitalinout_direction_obj_t digitalio_digitalinout_direction_out_obj;
 
 STATIC mp_obj_t digitalio_digitalinout_obj_get_direction(mp_obj_t self_in) {
-   digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   enum digitalinout_direction_t direction = common_hal_digitalio_digitalinout_get_direction(self);
-   if (direction == DIRECTION_IN) {
-       return (mp_obj_t)&digitalio_digitalinout_direction_in_obj;
-   }
-   return (mp_obj_t)&digitalio_digitalinout_direction_out_obj;
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    enum digitalinout_direction_t direction = common_hal_digitalio_digitalinout_get_direction(self);
+    if (direction == DIRECTION_IN) {
+        return (mp_obj_t)&digitalio_digitalinout_direction_in_obj;
+    }
+    return (mp_obj_t)&digitalio_digitalinout_direction_out_obj;
 }
 MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_get_direction_obj, digitalio_digitalinout_obj_get_direction);
 
@@ -225,7 +226,7 @@ const mp_obj_property_t digitalio_digitalinout_direction_obj = {
 
 //|   .. attribute:: value
 //|
-//|       The digital logic level of the pin.
+//|     The digital logic level of the pin.
 //|
 STATIC mp_obj_t digitalio_digitalinout_obj_get_value(mp_obj_t self_in) {
     digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -254,7 +255,7 @@ const mp_obj_property_t digitalio_digitalinout_value_obj = {
 
 //|   .. attribute:: drive_mode
 //|
-//|       Get or set the pin drive mode.
+//|     Get or set the pin drive mode.
 //|
 STATIC mp_obj_t digitalio_digitalinout_obj_get_drive_mode(mp_obj_t self_in) {
     digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -271,17 +272,17 @@ STATIC mp_obj_t digitalio_digitalinout_obj_get_drive_mode(mp_obj_t self_in) {
 MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_get_drive_mode_obj, digitalio_digitalinout_obj_get_drive_mode);
 
 STATIC mp_obj_t digitalio_digitalinout_obj_set_drive_mode(mp_obj_t self_in, mp_obj_t drive_mode) {
-   digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_IN) {
-       mp_raise_AttributeError("Drive mode not used when direction is input.");
-       return mp_const_none;
-   }
-   enum digitalinout_drive_mode_t c_drive_mode = DRIVE_MODE_PUSH_PULL;
-   if (drive_mode == &digitalio_digitalinout_drive_mode_open_drain_obj) {
-       c_drive_mode = DRIVE_MODE_OPEN_DRAIN;
-   }
-   common_hal_digitalio_digitalinout_set_drive_mode(self, c_drive_mode);
-   return mp_const_none;
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_IN) {
+        mp_raise_AttributeError("Drive mode not used when direction is input.");
+        return mp_const_none;
+    }
+    enum digitalinout_drive_mode_t c_drive_mode = DRIVE_MODE_PUSH_PULL;
+    if (drive_mode == &digitalio_digitalinout_drive_mode_open_drain_obj) {
+        c_drive_mode = DRIVE_MODE_OPEN_DRAIN;
+    }
+    common_hal_digitalio_digitalinout_set_drive_mode(self, c_drive_mode);
+    return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_2(digitalio_digitalinout_set_drive_mode_obj, digitalio_digitalinout_obj_set_drive_mode);
 
@@ -294,40 +295,40 @@ const mp_obj_property_t digitalio_digitalinout_drive_mode_obj = {
 
 //|   .. attribute:: pull
 //|
-//|       Get or set the pin pull.
+//|     Get or set the pin pull.
 //|
-//|       :raises AttributeError: if the direction is ~`Direction.OUT`.
+//|     :raises AttributeError: if the direction is ~`Direction.OUT`.
 //|
 STATIC mp_obj_t digitalio_digitalinout_obj_get_pull(mp_obj_t self_in) {
-   digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) {
-       mp_raise_AttributeError("Pull not used when direction is output.");
-       return mp_const_none;
-   }
-   enum digitalinout_pull_t pull = common_hal_digitalio_digitalinout_get_pull(self);
-   if (pull == PULL_UP) {
-       return (mp_obj_t)&digitalio_digitalinout_pull_up_obj;
-   } else if (pull == PULL_DOWN) {
-       return (mp_obj_t)&digitalio_digitalinout_pull_down_obj;
-   }
-   return (mp_obj_t)&mp_const_none_obj;
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) {
+        mp_raise_AttributeError("Pull not used when direction is output.");
+        return mp_const_none;
+    }
+    enum digitalinout_pull_t pull = common_hal_digitalio_digitalinout_get_pull(self);
+    if (pull == PULL_UP) {
+        return (mp_obj_t)&digitalio_digitalinout_pull_up_obj;
+    } else if (pull == PULL_DOWN) {
+        return (mp_obj_t)&digitalio_digitalinout_pull_down_obj;
+    }
+    return (mp_obj_t)&mp_const_none_obj;
 }
 MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_get_pull_obj, digitalio_digitalinout_obj_get_pull);
 
 STATIC mp_obj_t digitalio_digitalinout_obj_set_pull(mp_obj_t self_in, mp_obj_t pull_obj) {
-   digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) {
-       mp_raise_AttributeError("Pull not used when direction is output.");
-       return mp_const_none;
-   }
-   enum digitalinout_pull_t pull = PULL_NONE;
-   if (pull_obj == &digitalio_digitalinout_pull_up_obj) {
-       pull = PULL_UP;
-   } else if (pull_obj == &digitalio_digitalinout_pull_down_obj) {
-       pull = PULL_DOWN;
-   }
-   common_hal_digitalio_digitalinout_set_pull(self, pull);
-   return mp_const_none;
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) {
+        mp_raise_AttributeError("Pull not used when direction is output.");
+        return mp_const_none;
+    }
+    enum digitalinout_pull_t pull = PULL_NONE;
+    if (pull_obj == &digitalio_digitalinout_pull_up_obj) {
+        pull = PULL_UP;
+    } else if (pull_obj == &digitalio_digitalinout_pull_down_obj) {
+        pull = PULL_DOWN;
+    }
+    common_hal_digitalio_digitalinout_set_pull(self, pull);
+    return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_2(digitalio_digitalinout_set_pull_obj, digitalio_digitalinout_obj_set_pull);
 
diff --git a/shared-bindings/digitalio/__init__.c b/shared-bindings/digitalio/__init__.c
index 687110671..7767f236f 100644
--- a/shared-bindings/digitalio/__init__.c
+++ b/shared-bindings/digitalio/__init__.c
@@ -52,16 +52,17 @@
 //|     DigitalInOut
 //|
 //| All classes 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.
+//| 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 digitalio
 //|   from board import *
 //|
-//|   with digitalio.DigitalInOut(D13) as pin:
-//|     print(pin.value)
+//|   pin = digitalio.DigitalInOut(D13)
+//|   print(pin.value)
 //|
 //| This example will initialize the the device, read
 //| :py:data:`~digitalio.DigitalInOut.value` and then
@@ -73,9 +74,9 @@
 //|   from board import *
 //|   import time
 //|
-//|   with digitalio.DigitalInOut(D13) as led:
-//|     led.switch_to_output()
-//|     while True:
+//|   led = digitalio.DigitalInOut(D13)
+//|   led.direction = digitalio.DigitalInOut.Direction.OUT
+//|   while True:
 //|       led.value = True
 //|       time.sleep(0.1)
 //|       led.value = False
diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst
index beb7ba68b..e44c60f83 100644
--- a/shared-bindings/index.rst
+++ b/shared-bindings/index.rst
@@ -7,6 +7,8 @@ in a port if no underlying hardware support is present or if flash space is
 limited. For example, a microcontroller without analog features will not have
 `analogio`.
 
+.. _module-support-matrix:
+
 Support Matrix
 ---------------
 
diff --git a/shared-bindings/pulseio/PWMOut.c b/shared-bindings/pulseio/PWMOut.c
index 850033502..80036ae72 100644
--- a/shared-bindings/pulseio/PWMOut.c
+++ b/shared-bindings/pulseio/PWMOut.c
@@ -60,16 +60,16 @@
 //|     import pulseio
 //|     import board
 //|
-//|     with pulseio.PWMOut(board.D13) as pwm:     # output on D13
-//|       pwm.duty_cycle = 2 ** 15                  # Cycles the pin with 50% duty cycle (half of 2 ** 16) at the default 500hz
+//|     pwm = pulseio.PWMOut(board.D13)     # output on D13
+//|     pwm.duty_cycle = 2 ** 15            # Cycles the pin with 50% duty cycle (half of 2 ** 16) at the default 500hz
 //|
 //|   PWM at specific frequency (servos and motors)::
 //|
 //|     import pulseio
 //|     import board
 //|
-//|     with pulseio.PWMOut(board.D13, frequency=50) as pwm:
-//|       pwm.duty_cycle = 2 ** 15                  # Cycles the pin with 50% duty cycle (half of 2 ** 16) at 50hz
+//|     pwm = pulseio.PWMOut(board.D13, frequency=50)
+//|     pwm.duty_cycle = 2 ** 15                  # Cycles the pin with 50% duty cycle (half of 2 ** 16) at 50hz
 //|
 //|   Variable frequency (usually tones)::
 //|
@@ -77,10 +77,10 @@
 //|     import board
 //|     import time
 //|
-//|     with pulseio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=440, variable_frequency=True) as pwm:
-//|       time.sleep(0.2)
-//|       pwm.frequency = 880
-//|       time.sleep(0.1)
+//|     pwm = pulseio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=440, variable_frequency=True)
+//|     time.sleep(0.2)
+//|     pwm.frequency = 880
+//|     time.sleep(0.1)
 //|
 STATIC mp_obj_t pulseio_pwmout_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
     mp_arg_check_num(n_args, n_kw, 1, MP_OBJ_FUN_ARGS_MAX, true);
@@ -131,7 +131,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pwmout_deinit_obj, pulseio_pwmout_deini
 
 //|   .. 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 pulseio_pwmout_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/pulseio/PulseIn.c b/shared-bindings/pulseio/PulseIn.c
index a5d5d0c72..89196e841 100644
--- a/shared-bindings/pulseio/PulseIn.c
+++ b/shared-bindings/pulseio/PulseIn.c
@@ -61,22 +61,23 @@
 //|     import pulseio
 //|     import board
 //|
-//|     with pulseio.PulseIn(board.D7) as pulses:
-//|         # Wait for an active pulse
-//|         while len(pulses) == 0:
-//|             pass
-//|         # Pause while we do something with the pulses
-//|         pulses.pause()
+//|     pulses = pulseio.PulseIn(board.D7)
 //|
-//|         # Print the pulses. pulses[0] is an active pulse unless the length
-//|         # reached max length and idle pulses are recorded.
-//|         print(pulses)
+//|     # Wait for an active pulse
+//|     while len(pulses) == 0:
+//|         pass
+//|     # Pause while we do something with the pulses
+//|     pulses.pause()
 //|
-//|         # Clear the rest
-//|         pulse_in.clear()
+//|     # Print the pulses. pulses[0] is an active pulse unless the length
+//|     # reached max length and idle pulses are recorded.
+//|     print(pulses)
 //|
-//|         # Resume with an 80 microsecond active pulse
-//|         pulse_in.resume(80)
+//|     # Clear the rest
+//|     pulse_in.clear()
+//|
+//|     # Resume with an 80 microsecond active pulse
+//|     pulse_in.resume(80)
 //|
 STATIC mp_obj_t pulseio_pulsein_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);
@@ -122,7 +123,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pulsein_deinit_obj, pulseio_pulsein_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 pulseio_pulsein_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/pulseio/PulseOut.c b/shared-bindings/pulseio/PulseOut.c
index 7b05e704c..0b1391f74 100644
--- a/shared-bindings/pulseio/PulseOut.c
+++ b/shared-bindings/pulseio/PulseOut.c
@@ -54,15 +54,15 @@
 //|     import pulseio
 //|     import board
 //|
-//|     with pulseio.PWMOut(board.D13, duty_cycle=2 ** 15) as pwm:
-//|         pulse = pulseio.PulseOut(pwm)
-//|         #                             on   off     on     off   on
-//|         pulses = array.array('H', [65000, 1000, 65000, 65000, 1000])
-//|         pulse.send(pulses)
+//|     pwm = pulseio.PWMOut(board.D13, duty_cycle=2 ** 15)
+//|     pulse = pulseio.PulseOut(pwm)
+//|     #                             on   off     on     off   on
+//|     pulses = array.array('H', [65000, 1000, 65000, 65000, 1000])
+//|     pulse.send(pulses)
 //|
-//|         # Modify the array of pulses.
-//|         pulses[0] = 200
-//|         pulse.send(pulses)
+//|     # Modify the array of pulses.
+//|     pulses[0] = 200
+//|     pulse.send(pulses)
 //|
 STATIC mp_obj_t pulseio_pulseout_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
     mp_arg_check_num(n_args, n_kw, 1, 1, true);
@@ -100,7 +100,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pulseout_deinit_obj, pulseio_pulseout_d
 
 //|   .. 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 pulseio_pulseout_obj___exit__(size_t n_args, const mp_obj_t *args) {
     (void)n_args;
diff --git a/shared-bindings/pulseio/__init__.c b/shared-bindings/pulseio/__init__.c
index bf3272108..1114b604b 100644
--- a/shared-bindings/pulseio/__init__.c
+++ b/shared-bindings/pulseio/__init__.c
@@ -53,9 +53,15 @@
 //|     PulseOut
 //|     PWMOut
 //|
-//| 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.
+
+//| .. warning:: This module is not available in some SAMD21 builds. See the
+//|   :ref:`module-support-matrix` for more info.
+//|
+
+//| 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::
 //|
@@ -63,13 +69,15 @@
 //|   import time
 //|   from board import *
 //|
-//|   with pulseio.PWMOut(D13) as pin:
-//|     pin.duty_cycle = 2 ** 15
-//|     time.sleep(0.1)
+//|   pwm = pulseio.PWMOut(D13)
+//|   pwm.duty_cycle = 2 ** 15
+//|   time.sleep(0.1)
 //|
 //| This example will initialize the the device, set
-//| :py:data:`~pulseio.PWMOut.duty_cycle`, sleep 0.1 seconds and then
-//| :py:meth:`~pulseio.PWMOut.deinit` the hardware.
+//| :py:data:`~pulseio.PWMOut.duty_cycle`, and then sleep 0.1 seconds.
+//| CircuitPython will automatically turn off the PWM when it resets all
+//| hardware after program completion. Use ``deinit()`` or a ``with`` statement
+//| to do it yourself.
 //|
 
 STATIC const mp_rom_map_elem_t pulseio_module_globals_table[] = {
diff --git a/shared-bindings/time/__init__.c b/shared-bindings/time/__init__.c
index b258b3bbd..9ad631a63 100644
--- a/shared-bindings/time/__init__.c
+++ b/shared-bindings/time/__init__.c
@@ -39,7 +39,7 @@
 //|   :synopsis: time and timing related functions
 //|   :platform: SAMD21
 //|
-//| The `time` module is a strict subset of the CPython `time` module. So, code
+//| The `time` module is a strict subset of the CPython `cpython:time` module. So, code
 //| written in MicroPython will work in CPython but not necessarily the other
 //| way around.
 //|
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[] = {
diff --git a/shared-bindings/usb_hid/Device.c b/shared-bindings/usb_hid/Device.c
index 3a3cc5170..7e5d3d9e8 100644
--- a/shared-bindings/usb_hid/Device.c
+++ b/shared-bindings/usb_hid/Device.c
@@ -55,13 +55,13 @@ STATIC mp_obj_t usb_hid_device_make_new(const mp_obj_type_t *type,
 //|     Send a HID report.
 //|
 STATIC mp_obj_t usb_hid_device_send_report(mp_obj_t self_in, mp_obj_t buffer) {
-   usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);
 
-   mp_buffer_info_t bufinfo;
-   mp_get_buffer_raise(buffer, &bufinfo, MP_BUFFER_READ);
+    mp_buffer_info_t bufinfo;
+    mp_get_buffer_raise(buffer, &bufinfo, MP_BUFFER_READ);
 
-   common_hal_usb_hid_device_send_report(self, ((uint8_t*) bufinfo.buf), bufinfo.len);
-   return mp_const_none;
+    common_hal_usb_hid_device_send_report(self, ((uint8_t*) bufinfo.buf), bufinfo.len);
+    return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_2(usb_hid_device_send_report_obj, usb_hid_device_send_report);
 
@@ -73,8 +73,8 @@ MP_DEFINE_CONST_FUN_OBJ_2(usb_hid_device_send_report_obj, usb_hid_device_send_re
 //|     :rtype: int
 //|
 STATIC mp_obj_t usb_hid_device_obj_get_usage_page(mp_obj_t self_in) {
-   usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   return MP_OBJ_NEW_SMALL_INT(common_hal_usb_hid_device_get_usage_page(self));
+    usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    return MP_OBJ_NEW_SMALL_INT(common_hal_usb_hid_device_get_usage_page(self));
 }
 MP_DEFINE_CONST_FUN_OBJ_1(usb_hid_device_get_usage_page_obj, usb_hid_device_obj_get_usage_page);
 
@@ -95,8 +95,8 @@ const mp_obj_property_t usb_hid_device_usage_page_obj = {
 //|     :rtype: int
 //|
 STATIC mp_obj_t usb_hid_device_obj_get_usage(mp_obj_t self_in) {
-   usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   return MP_OBJ_NEW_SMALL_INT(common_hal_usb_hid_device_get_usage(self));
+    usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    return MP_OBJ_NEW_SMALL_INT(common_hal_usb_hid_device_get_usage(self));
 }
 MP_DEFINE_CONST_FUN_OBJ_1(usb_hid_device_get_usage_obj,
                           usb_hid_device_obj_get_usage);
diff --git a/shared-bindings/usb_hid/__init__.c b/shared-bindings/usb_hid/__init__.c
index a870cb4a1..3ad5b06e0 100644
--- a/shared-bindings/usb_hid/__init__.c
+++ b/shared-bindings/usb_hid/__init__.c
@@ -41,10 +41,6 @@
 //| The `usb_hid` module allows you to output data as a HID device.
 //|
 
-//| .. warning:: This module may be dropped from builds without external flash
-//|   in the future. Please file an issue if this a problem and explain why.
-//|
-
 //| .. attribute:: usb_hid.devices
 //|
 //|   Tuple of all active HID device interfaces.