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

4 files changed, 52 insertions, 40 deletions

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[] = {