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

conf.py

@@ -319,6 +319,6 @@ texinfo_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/3/': None,
+intersphinx_mapping = {"cpython": ('https://docs.python.org/3/', None),
-                       'https://circuitpython.readthedocs.io/projects/bus_device/en/latest/': None,
+                       "bus_device": ('https://circuitpython.readthedocs.io/projects/bus_device/en/latest/', None),
-                       'https://circuitpython.readthedocs.io/projects/register/en/latest/': None}
+                       "register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None)}

docs/design_guide.rst

@@ -33,6 +33,8 @@ not have the ``adafruit_`` module or package prefix.
 
 Both should have the CircuitPython repository topic on GitHub.
 
+.. _lifetime-and-contextmanagers:
+
 Lifetime and ContextManagers
 --------------------------------------------------------------------------------
 
@@ -41,6 +43,49 @@ device requires deinitialization, then provide it through ``deinit()`` and also
 provide ``__enter__`` and ``__exit__`` to create a context manager usable with
 ``with``.
 
+For example, a user can then use ``deinit()```::
+
+    import digitalio
+    import board
+
+    led = digitalio.DigitalInOut(board.D13)
+    led.direction = digitalio.DigitalInOut.Direction.OUT
+
+    for i in range(10):
+        led.value = True
+        time.sleep(0.5)
+
+        led.value = False
+        time.sleep(0.5)
+    led.deinit()
+
+This will deinit the underlying hardware at the end of the program as long as no
+exceptions occur.
+
+Alternatively, using a ``with`` statement ensures that the hardware is deinitialized::
+
+    import digitalio
+    import board
+
+    with digitalio.DigitalInOut(board.D13) as led:
+        led.direction = digitalio.DigitalInOut.Direction.OUT
+
+        for i in range(10):
+            led.value = True
+            time.sleep(0.5)
+
+            led.value = False
+            time.sleep(0.5)
+
+Python's ``with`` statement ensures that the deinit code is run regardless of
+whether the code within the with statement executes without exceptions.
+
+For small programs like the examples this isn't a major concern because all
+user usable hardware is reset after programs are run or the REPL is run. However,
+for more complex programs that may use hardware intermittently and may also
+handle exceptions on their own, deinitializing the hardware using a with
+statement will ensure hardware isn't enabled longer than needed.
+
 Verify your device
 --------------------------------------------------------------------------------
 

shared-bindings/analogio/AnalogIn.c

@@ -45,8 +45,8 @@
 //|    import analogio
 //|    from board import *
 //|
-//|    with analogio.AnalogIn(A1) as adc:
+//|    adc = analogio.AnalogIn(A1)
-//|      val = adc.value
+//|    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;

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 = analogio.AnalogOut(pin.PA02)          # output on pin PA02
-//|       dac.value = 32768                           # makes PA02 1.65V
+//|     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;

shared-bindings/analogio/__init__.c

@@ -53,21 +53,24 @@
 //|     AnalogIn
 //|     AnalogOut
 //|
-//| All libraries change hardware state and should be deinitialized when they
+//| 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
+//| are no longer needed if the program continues after use. To do so, either
-//| context manager.
+//| 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:
+//|   pin = analogio.AnalogIn(A0)
-//|     print(pin.value)
+//|   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[] = {

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 = audioio.AudioOut(board.SPEAKER, sin_wave)
-//|         sample.play(loop=True)
+//|     sample.play(loop=True)
-//|         time.sleep(1)
+//|     time.sleep(1)
-//|         sample.stop()
+//|     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;

shared-bindings/audioio/__init__.c

@@ -49,9 +49,10 @@
 //|
 //|     AudioOut
 //|
-//| All libraries change hardware state and should be deinitialized when they
+//| 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
+//| are no longer needed if the program continues after use. To do so, either
-//| context manager.
+//| 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[] = {

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;

shared-bindings/bitbangio/OneWire.c

@@ -55,11 +55,11 @@
 //|     import bitbangio
 //|     import board
 //|
-//|     with bitbangio.OneWire(board.D7) as onewire:
+//|     onewire = bitbangio.OneWire(board.D7)
-//|       onewire.reset()
+//|     onewire.reset()
-//|       onewire.write_bit(True)
+//|     onewire.write_bit(True)
-//|       onewire.write_bit(False)
+//|     onewire.write_bit(False)
-//|       print(onewire.read_bit())
+//|     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;

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;

shared-bindings/bitbangio/__init__.c

@@ -64,21 +64,24 @@
 //|     OneWire
 //|     SPI
 //|
-//| All libraries change hardware state and should be deinitialized when they
+//| 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
+//| are no longer needed if the program continues after use. To do so, either
-//| context manager.
+//| 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 = bitbangio.I2C(SCL, SDA)
-//|     i2c.scan()
+//|   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[] = {

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);
+    busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   common_hal_busio_i2c_deinit(self);
+    common_hal_busio_i2c_deinit(self);
-   return mp_const_none;
+    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);
+    busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   check_lock(self);
+    check_lock(self);
-   mp_obj_t list = mp_obj_new_list(0, NULL);
+    mp_obj_t list = mp_obj_new_list(0, NULL);
-   // 7-bit addresses 0b0000xxx and 0b1111xxx are reserved
+    // 7-bit addresses 0b0000xxx and 0b1111xxx are reserved
-   for (int addr = 0x08; addr < 0x78; ++addr) {
+    for (int addr = 0x08; addr < 0x78; ++addr) {
-       bool success = common_hal_busio_i2c_probe(self, addr);
+        bool success = common_hal_busio_i2c_probe(self, addr);
-       if (success) {
+        if (success) {
-           mp_obj_list_append(list, MP_OBJ_NEW_SMALL_INT(addr));
+            mp_obj_list_append(list, MP_OBJ_NEW_SMALL_INT(addr));
-       }
+        }
-   }
+    }
-   return list;
+    return list;
 }
 MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan);
 

shared-bindings/busio/OneWire.c

@@ -55,11 +55,11 @@
 //|     import busio
 //|     import board
 //|
-//|     with busio.OneWire(board.D7) as onewire:
+//|     onewire = busio.OneWire(board.D7)
-//|       onewire.reset()
+//|     onewire.reset()
-//|       onewire.write_bit(True)
+//|     onewire.write_bit(True)
-//|       onewire.write_bit(False)
+//|     onewire.write_bit(False)
-//|       print(onewire.read_bit())
+//|     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;

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;

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);
+    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);
+    busio_uart_obj_t *self = m_new_obj(busio_uart_obj_t);
-   self->base.type = &busio_uart_type;
+    self->base.type = &busio_uart_type;
-   mp_map_t kw_args;
+    mp_map_t kw_args;
-   mp_map_init_fixed_table(&kw_args, n_kw, pos_args + n_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};
+    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[] = {
+    static const mp_arg_t allowed_args[] = {
-       { MP_QSTR_tx, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_tx, MP_ARG_REQUIRED | MP_ARG_OBJ },
-       { MP_QSTR_rx, 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_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_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_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_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_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_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_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);
+    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);
+    assert_pin(args[ARG_rx].u_obj, true);
-   const mcu_pin_obj_t* rx = MP_OBJ_TO_PTR(args[ARG_rx].u_obj);
+    const mcu_pin_obj_t* rx = MP_OBJ_TO_PTR(args[ARG_rx].u_obj);
-   assert_pin_free(rx);
+    assert_pin_free(rx);
 
-   assert_pin(args[ARG_tx].u_obj, true);
+    assert_pin(args[ARG_tx].u_obj, true);
-   const mcu_pin_obj_t* tx = MP_OBJ_TO_PTR(args[ARG_tx].u_obj);
+    const mcu_pin_obj_t* tx = MP_OBJ_TO_PTR(args[ARG_tx].u_obj);
-   assert_pin_free(tx);
+    assert_pin_free(tx);
 
-   uint8_t bits = args[ARG_bits].u_int;
+    uint8_t bits = args[ARG_bits].u_int;
-   if (bits < 7 || bits > 9) {
+    if (bits < 7 || bits > 9) {
-       mp_raise_ValueError("bits must be 7, 8 or 9");
+        mp_raise_ValueError("bits must be 7, 8 or 9");
-   }
+    }
 
-   uart_parity_t parity = PARITY_NONE;
+    uart_parity_t parity = PARITY_NONE;
-   if (args[ARG_parity].u_obj == &busio_uart_parity_even_obj) {
+    if (args[ARG_parity].u_obj == &busio_uart_parity_even_obj) {
-       parity = PARITY_EVEN;
+        parity = PARITY_EVEN;
-   } else if (args[ARG_parity].u_obj == &busio_uart_parity_odd_obj) {
+    } else if (args[ARG_parity].u_obj == &busio_uart_parity_odd_obj) {
-       parity = PARITY_ODD;
+        parity = PARITY_ODD;
-   }
+    }
 
-   uint8_t stop = args[ARG_stop].u_int;
+    uint8_t stop = args[ARG_stop].u_int;
-   if (stop != 1 && stop != 2) {
+    if (stop != 1 && stop != 2) {
-       mp_raise_ValueError("stop must be 1 or 2");
+        mp_raise_ValueError("stop must be 1 or 2");
-   }
+    }
 
-   common_hal_busio_uart_construct(self, tx, rx,
+    common_hal_busio_uart_construct(self, tx, rx,
-       args[ARG_baudrate].u_int, bits, parity, stop, args[ARG_timeout].u_int,
+        args[ARG_baudrate].u_int, bits, parity, stop, args[ARG_timeout].u_int,
-       args[ARG_receiver_buffer_size].u_int);
+        args[ARG_receiver_buffer_size].u_int);
-   return (mp_obj_t)self;
+    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);
+    busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   common_hal_busio_uart_deinit(self);
+    common_hal_busio_uart_deinit(self);
-   return mp_const_none;
+    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;

shared-bindings/busio/__init__.c

@@ -65,21 +65,24 @@
 //|     SPI
 //|     UART
 //|
-//| All libraries change hardware state and should be deinitialized when they
+//| 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
+//| are no longer needed if the program continues after use. To do so, either
-//| context manager.
+//| 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 = busio.I2C(SCL, SDA)
-//|     i2c.scan()
+//|   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[] = {

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);
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   common_hal_digitalio_digitalinout_deinit(self);
+    common_hal_digitalio_digitalinout_deinit(self);
-   return mp_const_none;
+    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 };
+    enum { ARG_value, ARG_drive_mode };
-   static const mp_arg_t allowed_args[] = {
+    static const mp_arg_t allowed_args[] = {
-       { MP_QSTR_value,      MP_ARG_BOOL, {.u_bool = false} },
+        { 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} },
+        { 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]);
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
-   mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    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);
+    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;
+    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) {
+    if (args[ARG_drive_mode].u_rom_obj == &digitalio_digitalinout_drive_mode_open_drain_obj) {
-       drive_mode = DRIVE_MODE_OPEN_DRAIN;
+        drive_mode = DRIVE_MODE_OPEN_DRAIN;
-   }
+    }
-   // do the transfer
+    // do the transfer
-   common_hal_digitalio_digitalinout_switch_to_output(self, args[ARG_value].u_bool, drive_mode);
+    common_hal_digitalio_digitalinout_switch_to_output(self, args[ARG_value].u_bool, drive_mode);
-   return mp_const_none;
+    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 = digitalio.DigitalInOut(board.SLIDE_SWITCH)
-//|         switch.switch_to_input(pull=digitalio.DigitalInOut.Pull.UP)
+//|       switch.switch_to_input(pull=digitalio.DigitalInOut.Pull.UP)
-//|         # Or, after switch_to_input
+//|       # Or, after switch_to_input
-//|         switch.pull = digitalio.DigitalInOut.Pull.UP
+//|       switch.pull = digitalio.DigitalInOut.Pull.UP
-//|         print(switch.value)
+//|       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 };
+    enum { ARG_pull };
-   static const mp_arg_t allowed_args[] = {
+    static const mp_arg_t allowed_args[] = {
-       { MP_QSTR_pull, MP_ARG_OBJ, {.u_rom_obj = mp_const_none} },
+        { MP_QSTR_pull, MP_ARG_OBJ, {.u_rom_obj = mp_const_none} },
-   };
+    };
-   digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
-   mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    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);
+    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;
+    enum digitalinout_pull_t pull = PULL_NONE;
-   if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_up_obj) {
+    if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_up_obj) {
-       pull = PULL_UP;
+        pull = PULL_UP;
-   }else if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_down_obj) {
+    }else if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_down_obj) {
-       pull = PULL_DOWN;
+        pull = PULL_DOWN;
-   }
+    }
-   // do the transfer
+    // do the transfer
-   common_hal_digitalio_digitalinout_switch_to_input(self, pull);
+    common_hal_digitalio_digitalinout_switch_to_input(self, pull);
-   return mp_const_none;
+    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
+//|     Setting this will use the defaults from the corresponding
-//|       :py:meth:`switch_to_input` or :py:meth:`switch_to_output` method. If
+//|     :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
+//|     you want to set pull, value or drive mode prior to switching, then use
-//|       those methods instead.
+//|     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);
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   enum digitalinout_direction_t direction = common_hal_digitalio_digitalinout_get_direction(self);
+    enum digitalinout_direction_t direction = common_hal_digitalio_digitalinout_get_direction(self);
-   if (direction == DIRECTION_IN) {
+    if (direction == DIRECTION_IN) {
-       return (mp_obj_t)&digitalio_digitalinout_direction_in_obj;
+        return (mp_obj_t)&digitalio_digitalinout_direction_in_obj;
-   }
+    }
-   return (mp_obj_t)&digitalio_digitalinout_direction_out_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);
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_IN) {
+    if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_IN) {
-       mp_raise_AttributeError("Drive mode not used when direction is input.");
+        mp_raise_AttributeError("Drive mode not used when direction is input.");
-       return mp_const_none;
+        return mp_const_none;
-   }
+    }
-   enum digitalinout_drive_mode_t c_drive_mode = DRIVE_MODE_PUSH_PULL;
+    enum digitalinout_drive_mode_t c_drive_mode = DRIVE_MODE_PUSH_PULL;
-   if (drive_mode == &digitalio_digitalinout_drive_mode_open_drain_obj) {
+    if (drive_mode == &digitalio_digitalinout_drive_mode_open_drain_obj) {
-       c_drive_mode = DRIVE_MODE_OPEN_DRAIN;
+        c_drive_mode = DRIVE_MODE_OPEN_DRAIN;
-   }
+    }
-   common_hal_digitalio_digitalinout_set_drive_mode(self, c_drive_mode);
+    common_hal_digitalio_digitalinout_set_drive_mode(self, c_drive_mode);
-   return mp_const_none;
+    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);
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) {
+    if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) {
-       mp_raise_AttributeError("Pull not used when direction is output.");
+        mp_raise_AttributeError("Pull not used when direction is output.");
-       return mp_const_none;
+        return mp_const_none;
-   }
+    }
-   enum digitalinout_pull_t pull = common_hal_digitalio_digitalinout_get_pull(self);
+    enum digitalinout_pull_t pull = common_hal_digitalio_digitalinout_get_pull(self);
-   if (pull == PULL_UP) {
+    if (pull == PULL_UP) {
-       return (mp_obj_t)&digitalio_digitalinout_pull_up_obj;
+        return (mp_obj_t)&digitalio_digitalinout_pull_up_obj;
-   } else if (pull == PULL_DOWN) {
+    } else if (pull == PULL_DOWN) {
-       return (mp_obj_t)&digitalio_digitalinout_pull_down_obj;
+        return (mp_obj_t)&digitalio_digitalinout_pull_down_obj;
-   }
+    }
-   return (mp_obj_t)&mp_const_none_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);
+    digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
-   if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) {
+    if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) {
-       mp_raise_AttributeError("Pull not used when direction is output.");
+        mp_raise_AttributeError("Pull not used when direction is output.");
-       return mp_const_none;
+        return mp_const_none;
-   }
+    }
-   enum digitalinout_pull_t pull = PULL_NONE;
+    enum digitalinout_pull_t pull = PULL_NONE;
-   if (pull_obj == &digitalio_digitalinout_pull_up_obj) {
+    if (pull_obj == &digitalio_digitalinout_pull_up_obj) {
-       pull = PULL_UP;
+        pull = PULL_UP;
-   } else if (pull_obj == &digitalio_digitalinout_pull_down_obj) {
+    } else if (pull_obj == &digitalio_digitalinout_pull_down_obj) {
-       pull = PULL_DOWN;
+        pull = PULL_DOWN;
-   }
+    }
-   common_hal_digitalio_digitalinout_set_pull(self, pull);
+    common_hal_digitalio_digitalinout_set_pull(self, pull);
-   return mp_const_none;
+    return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_2(digitalio_digitalinout_set_pull_obj, digitalio_digitalinout_obj_set_pull);
 

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
+//| are no longer needed if the program continues after use. To do so, either
-//| context manager.
+//| 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:
+//|   pin = digitalio.DigitalInOut(D13)
-//|     print(pin.value)
+//|   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 = digitalio.DigitalInOut(D13)
-//|     led.switch_to_output()
+//|   led.direction = digitalio.DigitalInOut.Direction.OUT
-//|     while True:
+//|   while True:
 //|       led.value = True
 //|       time.sleep(0.1)
 //|       led.value = False

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
 ---------------
 

shared-bindings/pulseio/PWMOut.c

@@ -60,16 +60,16 @@
 //|     import pulseio
 //|     import board
 //|
-//|     with pulseio.PWMOut(board.D13) as pwm:     # output on D13
+//|     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.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 = pulseio.PWMOut(board.D13, frequency=50)
-//|       pwm.duty_cycle = 2 ** 15                  # Cycles the pin with 50% duty cycle (half of 2 ** 16) at 50hz
+//|     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:
+//|     pwm = pulseio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=440, variable_frequency=True)
-//|       time.sleep(0.2)
+//|     time.sleep(0.2)
-//|       pwm.frequency = 880
+//|     pwm.frequency = 880
-//|       time.sleep(0.1)
+//|     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;

shared-bindings/pulseio/PulseIn.c

@@ -61,22 +61,23 @@
 //|     import pulseio
 //|     import board
 //|
-//|     with pulseio.PulseIn(board.D7) as pulses:
+//|     pulses = pulseio.PulseIn(board.D7)
-//|         # Wait for an active pulse
-//|         while len(pulses) == 0:
-//|             pass
-//|         # Pause while we do something with the pulses
-//|         pulses.pause()
 //|
-//|         # Print the pulses. pulses[0] is an active pulse unless the length
+//|     # Wait for an active pulse
-//|         # reached max length and idle pulses are recorded.
+//|     while len(pulses) == 0:
-//|         print(pulses)
+//|         pass
+//|     # Pause while we do something with the pulses
+//|     pulses.pause()
 //|
-//|         # Clear the rest
+//|     # Print the pulses. pulses[0] is an active pulse unless the length
-//|         pulse_in.clear()
+//|     # reached max length and idle pulses are recorded.
+//|     print(pulses)
 //|
-//|         # Resume with an 80 microsecond active pulse
+//|     # Clear the rest
-//|         pulse_in.resume(80)
+//|     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;

shared-bindings/pulseio/PulseOut.c

@@ -54,15 +54,15 @@
 //|     import pulseio
 //|     import board
 //|
-//|     with pulseio.PWMOut(board.D13, duty_cycle=2 ** 15) as pwm:
+//|     pwm = pulseio.PWMOut(board.D13, duty_cycle=2 ** 15)
-//|         pulse = pulseio.PulseOut(pwm)
+//|     pulse = pulseio.PulseOut(pwm)
-//|         #                             on   off     on     off   on
+//|     #                             on   off     on     off   on
-//|         pulses = array.array('H', [65000, 1000, 65000, 65000, 1000])
+//|     pulses = array.array('H', [65000, 1000, 65000, 65000, 1000])
-//|         pulse.send(pulses)
+//|     pulse.send(pulses)
 //|
-//|         # Modify the array of pulses.
+//|     # Modify the array of pulses.
-//|         pulses[0] = 200
+//|     pulses[0] = 200
-//|         pulse.send(pulses)
+//|     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;

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
+//| .. warning:: This module is not available in some SAMD21 builds. See the
-//| context manager.
+//|   :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:
+//|   pwm = pulseio.PWMOut(D13)
-//|     pin.duty_cycle = 2 ** 15
+//|   pwm.duty_cycle = 2 ** 15
-//|     time.sleep(0.1)
+//|   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:data:`~pulseio.PWMOut.duty_cycle`, and then sleep 0.1 seconds.
-//| :py:meth:`~pulseio.PWMOut.deinit` the hardware.
+//| 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[] = {

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.
 //|

shared-bindings/touchio/TouchIn.c

@@ -45,9 +45,10 @@
 //|    import touchio
 //|    from board import *
 //|
-//|    with touchio.TouchIn(A1) as touch:
+//|    touch = touchio.TouchIn(A1)
-//|      if touch.value:
+//|    while True:
-//|        print("touched!")
+//|        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;

shared-bindings/touchio/__init__.c

@@ -52,21 +52,21 @@
 //|
 //|     TouchIn
 //|
-//| All libraries change hardware state and should be deinitialized when they
+//| 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
+//| are no longer needed if the program continues after use. To do so, either
-//| context manager.
+//| 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:
+//|   touch_pin = touchio.TouchIn(D6)
-//|     print(touch_pin.value)
+//|   print(touch_pin.value)
 //|
-//| This example will initialize the the device, run
+//| This example will initialize the the device, and print the
-//| :py:data:`~touchio.TouchIn.value` and then :py:meth:`~touchio.TouchIn.deinit`
+//| :py:data:`~touchio.TouchIn.value`.
-//| the hardware.
 //|
 
 STATIC const mp_rom_map_elem_t touchio_module_globals_table[] = {

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_buffer_info_t bufinfo;
-   mp_get_buffer_raise(buffer, &bufinfo, MP_BUFFER_READ);
+    mp_get_buffer_raise(buffer, &bufinfo, MP_BUFFER_READ);
 
-   common_hal_usb_hid_device_send_report(self, ((uint8_t*) bufinfo.buf), bufinfo.len);
+    common_hal_usb_hid_device_send_report(self, ((uint8_t*) bufinfo.buf), bufinfo.len);
-   return mp_const_none;
+    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);
+    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));
+    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);
+    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));
+    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);

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.