Did math, microcontroller, and multiterminal

6 files changed, 184 insertions, 195 deletions

diff --git a/shared-bindings/math/__init__.c b/shared-bindings/math/__init__.c
index 0bf8047c9..755bf7589 100644
--- a/shared-bindings/math/__init__.c
+++ b/shared-bindings/math/__init__.c
@@ -38,7 +38,7 @@
 #define MP_PI MICROPY_FLOAT_CONST(3.14159265358979323846)
 
 
-//| :mod:`math` --- mathematical functions
+//| """:mod:`math` --- mathematical functions
 //| ========================================================
 //|
 //| .. module:: math
@@ -46,7 +46,7 @@
 //|   :platform: SAMD21/SAMD51
 //|
 //| The `math` module provides some basic mathematical functions for
-//| working with floating-point numbers.
+//| working with floating-point numbers."""
 //|
 
 STATIC NORETURN void math_error(void) {
@@ -86,117 +86,113 @@ STATIC NORETURN void math_error(void) {
   //| Constants
   //| ---------
   //|
-  //| .. data:: e
+  //| e: Any = ...
+  //| """base of the natural logarithm"""
   //|
-  //|    base of the natural logarithm
-  //|
-  //| .. data:: pi
-  //|
-  //|    the ratio of a circle's circumference to its diameter
+  //| pi: Any = ...
+  //| """the ratio of a circle's circumference to its diameter"""
   //|
 
   //| Functions
   //| ---------
   //|
-  //| .. function:: acos(x)
-  //|
-  //|   Return the inverse cosine of ``x``.
-  //|
-  //| .. function:: asin(x)
-  //|
-  //|   Return the inverse sine of ``x``.
-  //|
-  //| .. function:: atan(x)
-  //|
-  //|   Return the inverse tangent of ``x``.
-  //|
-  //| .. function:: atan2(y,x)
-  //|
-  //|   Return the principal value of the inverse tangent of ``y/x``.
-  //|
-  //| .. function:: ceil(x)
-  //|
-  //|   Return an integer, being ``x`` rounded towards positive infinity.
-  //|
-  //| .. function:: copysign(x,y)
-  //|
-  //|   Return ``x`` with the sign of ``y``.
-  //|
-  //| .. function:: cos(x)
-  //|
-  //|   Return the cosine of ``x``.
-  //|
-  //| .. function:: degrees(x)
-  //|
-  //|   Return radians ``x`` converted to degrees.
-  //|
-  //| .. function:: exp(x)
-  //|
-  //|   Return the exponential of ``x``.
-  //|
-  //| .. function:: fabs(x)
-  //|
-  //|   Return the absolute value of ``x``.
-  //|
-  //| .. function:: floor(x)
-  //|
-  //|   Return an integer, being ``x`` rounded towards negative infinity.
-  //|
-  //| .. function:: fmod(x,y)
-  //|
-  //|   Return the remainder of ``x/y``.
-  //|
-  //| .. function:: frexp(x)
+  //| def acos(x: Any) -> Any:
+  //|     """Return the inverse cosine of ``x``."""
+  //|     ...
   //|
-  //|   Decomposes a floating-point number into its mantissa and exponent.
-  //|   The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e``
-  //|   exactly.  If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise
-  //|   the relation ``0.5 <= abs(m) < 1`` holds.
+  //| def asin(x: Any) -> Any:
+  //|     """Return the inverse sine of ``x``."""
+  //|     ...
   //|
-  //| .. function:: isfinite(x)
+  //| def atan(x: Any) -> Any:
+  //|     """Return the inverse tangent of ``x``."""
+  //|     ...
   //|
-  //|   Return ``True`` if ``x`` is finite.
+  //| def atan2(y: Any, x: Any) -> Any:
+  //|     """Return the principal value of the inverse tangent of ``y/x``."""
+  //|     ...
   //|
-  //| .. function:: isinf(x)
+  //| def ceil(x: Any) -> Any:
+  //|     """Return an integer, being ``x`` rounded towards positive infinity."""
+  //|     ...
   //|
-  //|   Return ``True`` if ``x`` is infinite.
+  //| def copysign(x: Any, y: Any) -> Any:
+  //|     """Return ``x`` with the sign of ``y``."""
+  //|     ...
   //|
-  //| .. function:: isnan(x)
+  //| def cos(x: Any) -> Any:
+  //|     """Return the cosine of ``x``."""
+  //|     ...
   //|
-  //|   Return ``True`` if ``x`` is not-a-number
+  //| def degrees(x: Any) -> Any:
+  //|     """Return radians ``x`` converted to degrees."""
+  //|     ...
   //|
-  //| .. function:: ldexp(x, exp)
+  //| def exp(x: Any) -> Any:
+  //|     """Return the exponential of ``x``."""
+  //|     ...
   //|
-  //|   Return ``x * (2**exp)``.
+  //| def fabs(x: Any) -> Any:
+  //|     """Return the absolute value of ``x``."""
+  //|     ...
   //|
-  //| .. function:: modf(x)
+  //| def floor(x: Any) -> Any:
+  //|     """Return an integer, being ``x`` rounded towards negative infinity."""
+  //|     ...
   //|
-  //|   Return a tuple of two floats, being the fractional and integral parts of
-  //|   ``x``.  Both return values have the same sign as ``x``.
+  //| def fmod(x: Any, y: Any) -> Any:
+  //|     """Return the remainder of ``x/y``."""
+  //|     ...
   //|
-  //| .. function:: pow(x, y)
+  //| def frexp(x: Any) -> Any:
+  //|     """Decomposes a floating-point number into its mantissa and exponent.
+  //|     The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e``
+  //|     exactly.  If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise
+  //|     the relation ``0.5 <= abs(m) < 1`` holds."""
+  //|     ...
   //|
-  //|   Returns ``x`` to the power of ``y``.
+  //| def isfinite(x: Any) -> Any:
+  //|     """Return ``True`` if ``x`` is finite."""
+  //|     ...
   //|
-  //| .. function:: radians(x)
+  //| def isinf(x: Any) -> Any:
+  //|     """Return ``True`` if ``x`` is infinite."""
+  //|     ...
   //|
-  //|   Return degrees ``x`` converted to radians.
+  //| def isnan(x: Any) -> Any:
+  //|     """Return ``True`` if ``x`` is not-a-number"""
+  //|     ...
   //|
-  //| .. function:: sin(x)
+  //| def ldexp(x: Any, exp: Any) -> Any:
+  //|     """Return ``x * (2**exp)``."""
+  //|     ...
   //|
-  //|   Return the sine of ``x``.
+  //| def modf(x: Any) -> Any:
+  //|     """Return a tuple of two floats, being the fractional and integral parts of
+  //|     ``x``.  Both return values have the same sign as ``x``."""
+  //|     ...
   //|
-  //| .. function:: sqrt(x)
+  //| def pow(x: Any, y: Any) -> Any:
+  //|     """Returns ``x`` to the power of ``y``."""
   //|
-  //|   Returns the square root of ``x``.
+  //| def radians(x: Any) -> Any:
+  //|     """Return degrees ``x`` converted to radians."""
   //|
-  //| .. function:: tan(x)
+  //| def sin(x: Any) -> Any:
+  //|     """Return the sine of ``x``."""
+  //|     ...
   //|
-  //|   Return the tangent of ``x``.
+  //| def sqrt(x: Any) -> Any:
+  //|     """Returns the square root of ``x``."""
+  //|     ...
   //|
-  //| .. function:: trunc(x)
+  //| def tan(x: Any) -> Any: ...
+  //|     """Return the tangent of ``x``."""
+  //|     ...
   //|
-  //|   Return an integer, being ``x`` rounded towards 0.
+  //| def trunc(x: Any) -> Any:
+  //|     """Return an integer, being ``x`` rounded towards 0."""
+  //|     ...
   //|
  MATH_FUN_1_ERRCOND(sqrt, sqrt, (x < (mp_float_t)0.0))
 
diff --git a/shared-bindings/microcontroller/Pin.c b/shared-bindings/microcontroller/Pin.c
index 67aecaf66..cad0d67b1 100644
--- a/shared-bindings/microcontroller/Pin.c
+++ b/shared-bindings/microcontroller/Pin.c
@@ -33,18 +33,19 @@
 #include "py/runtime.h"
 #include "supervisor/shared/translate.h"
 
-//| .. currentmodule:: microcontroller
+//| class Pin:
+//|     """.. currentmodule:: microcontroller
 //|
-//| :class:`Pin` --- Pin reference
-//| ------------------------------------------
+//|     :class:`Pin` --- Pin reference
+//|     ------------------------------------------
 //|
-//| Identifies an IO pin on the microcontroller.
+//|     Identifies an IO pin on the microcontroller."""
 //|
-//| .. class:: Pin()
-//|
-//|    Identifies an IO pin on the microcontroller. They are fixed by the
-//|    hardware so they cannot be constructed on demand. Instead, use
-//|    `board` or `microcontroller.pin` to reference the desired pin.
+//|     def __init__(self, ):
+//|         """Identifies an IO pin on the microcontroller. They are fixed by the
+//|         hardware so they cannot be constructed on demand. Instead, use
+//|         `board` or `microcontroller.pin` to reference the desired pin."""
+//|         ...
 //|
 
 static void get_pin_name(const mcu_pin_obj_t *self, qstr* package, qstr* module, qstr* name) {
diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c
index 023f063e0..dedb5a27c 100644
--- a/shared-bindings/microcontroller/Processor.c
+++ b/shared-bindings/microcontroller/Processor.c
@@ -34,29 +34,29 @@
 
 #include "py/runtime.h"
 
-//| .. currentmodule:: microcontroller
+//| class Processor:
+//|     """.. currentmodule:: microcontroller
 //|
-//| :class:`Processor` --- Microcontroller CPU information and control
-//| ------------------------------------------------------------------
+//|     :class:`Processor` --- Microcontroller CPU information and control
+//|     ------------------------------------------------------------------
 //|
-//| Get information about the microcontroller CPU and control it.
+//|     Get information about the microcontroller CPU and control it.
 //|
-//| Usage::
+//|     Usage::
 //|
-//|    import microcontroller
-//|    print(microcontroller.cpu.frequency)
-//|    print(microcontroller.cpu.temperature)
+//|        import microcontroller
+//|        print(microcontroller.cpu.frequency)
+//|        print(microcontroller.cpu.temperature)"""
 //|
 
-//| .. class:: Processor()
-//|
-//|     You cannot create an instance of `microcontroller.Processor`.
-//|     Use `microcontroller.cpu` to access the sole instance available.
+//|     def __init__(self, ):
+//|         """You cannot create an instance of `microcontroller.Processor`.
+//|         Use `microcontroller.cpu` to access the sole instance available."""
+//|         ...
 //|
 
-//|     .. attribute:: frequency
-//|
-//|       The CPU operating frequency as an `int`, in Hertz. (read-only)
+//|     frequency: Any = ...
+//|     """The CPU operating frequency as an `int`, in Hertz. (read-only)"""
 //|
 STATIC mp_obj_t mcu_processor_get_frequency(mp_obj_t self) {
     return mp_obj_new_int_from_uint(common_hal_mcu_processor_get_frequency());
@@ -72,11 +72,10 @@ const mp_obj_property_t mcu_processor_frequency_obj = {
     },
 };
 
-//|     .. attribute:: temperature
-//|
-//|       The on-chip temperature, in Celsius, as a float. (read-only)
+//|     temperature: Any = ...
+//|     """The on-chip temperature, in Celsius, as a float. (read-only)
 //|
-//|       Is `None` if the temperature is not available.
+//|     Is `None` if the temperature is not available."""
 //|
 STATIC mp_obj_t mcu_processor_get_temperature(mp_obj_t self) {
     float temperature = common_hal_mcu_processor_get_temperature();
@@ -93,9 +92,8 @@ const mp_obj_property_t mcu_processor_temperature_obj = {
     },
 };
 
-//|     .. attribute:: uid
-//|
-//|       The unique id (aka serial number) of the chip as a `bytearray`. (read-only)
+//|     uid: Any = ...
+//|     """The unique id (aka serial number) of the chip as a `bytearray`. (read-only)"""
 //|
 STATIC mp_obj_t mcu_processor_get_uid(mp_obj_t self) {
     uint8_t raw_id[COMMON_HAL_MCU_PROCESSOR_UID_LENGTH];
@@ -113,11 +111,10 @@ const mp_obj_property_t mcu_processor_uid_obj = {
     },
 };
 
-//|     .. attribute:: voltage
-//|
-//|       The input voltage to the microcontroller, as a float. (read-only)
+//|     voltage: Any = ...
+//|     """The input voltage to the microcontroller, as a float. (read-only)
 //|
-//|       Is `None` if the voltage is not available.
+//|     Is `None` if the voltage is not available."""
 //|
 STATIC mp_obj_t mcu_processor_get_voltage(mp_obj_t self) {
     float voltage = common_hal_mcu_processor_get_voltage();
diff --git a/shared-bindings/microcontroller/RunMode.c b/shared-bindings/microcontroller/RunMode.c
index 913242ad2..df3ff4186 100644
--- a/shared-bindings/microcontroller/RunMode.c
+++ b/shared-bindings/microcontroller/RunMode.c
@@ -26,34 +26,31 @@
 
 #include "shared-bindings/microcontroller/RunMode.h"
 
-//| .. currentmodule:: microcontroller
+//| class RunMode:
+//|     """.. currentmodule:: microcontroller
 //|
-//| :class:`RunMode` -- run state of the microcontroller
-//| =============================================================
+//|     :class:`RunMode` -- run state of the microcontroller
+//|     ============================================================="""
 //|
-//| .. class:: RunMode()
+//|     def __init__(self, ):
+//|         """Enum-like class to define the run mode of the microcontroller and
+//|         CircuitPython."""
 //|
-//|     Enum-like class to define the run mode of the microcontroller and
-//|     CircuitPython.
+//|     NORMAL: Any = ...
+//|     """Run CircuitPython as normal.
 //|
-//|     .. attribute:: NORMAL
+//|     :type microcontroller.RunMode:"""
 //|
-//|       Run CircuitPython as normal.
+//|     SAFE_MODE: Any = ...
+//|     """Run CircuitPython in safe mode. User code will not be run and the
+//|     file system will be writeable over USB.
 //|
-//|       :type microcontroller.RunMode:
+//|     :type microcontroller.RunMode:"""
 //|
-//|     .. attribute:: SAFE_MODE
+//|     BOOTLOADER: Any = ...
+//|     """Run the bootloader.
 //|
-//|       Run CircuitPython in safe mode. User code will not be run and the
-//|       file system will be writeable over USB.
-//|
-//|       :type microcontroller.RunMode:
-//|
-//|     .. attribute:: BOOTLOADER
-//|
-//|       Run the bootloader.
-//|
-//|       :type microcontroller.RunMode:
+//|     :type microcontroller.RunMode:"""
 //|
 const mp_obj_type_t mcu_runmode_type;
 
diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c
index 090c4564d..75b763980 100644
--- a/shared-bindings/microcontroller/__init__.c
+++ b/shared-bindings/microcontroller/__init__.c
@@ -42,7 +42,7 @@
 #include "py/runtime.h"
 #include "supervisor/shared/translate.h"
 
-//| :mod:`microcontroller` --- Pin references and cpu functionality
+//| """:mod:`microcontroller` --- Pin references and cpu functionality
 //| ================================================================
 //|
 //| .. module:: microcontroller
@@ -59,24 +59,23 @@
 //|
 //|     Pin
 //|     Processor
-//|     RunMode
+//|     RunMode"""
 //|
 
-//| .. data:: cpu
-//|
-//|   CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency``
-//|   (clock frequency).
-//|   This object is the sole instance of `microcontroller.Processor`.
+//| cpu: Any = ... 
+//| """CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency``
+//| (clock frequency).
+//| This object is the sole instance of `microcontroller.Processor`."""
 //|
 
-//| .. function:: delay_us(delay)
-//|
-//|   Dedicated delay method used for very short delays. **Do not** do long delays
-//|   because this stops all other functions from completing. Think of this as an empty
-//|   ``while`` loop that runs for the specified ``(delay)`` time. If you have other
-//|   code or peripherals (e.g audio recording) that require specific timing or
-//|   processing while you are waiting, explore a different avenue such as using
-//|   `time.sleep()`.
+//| def delay_us(delay: Any) -> Any:
+//|     """Dedicated delay method used for very short delays. **Do not** do long delays
+//|     because this stops all other functions from completing. Think of this as an empty
+//|     ``while`` loop that runs for the specified ``(delay)`` time. If you have other
+//|     code or peripherals (e.g audio recording) that require specific timing or
+//|     processing while you are waiting, explore a different avenue such as using
+//|     `time.sleep()`."""
+//|     ...
 //|
 STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) {
     uint32_t delay = mp_obj_get_int(delay_obj);
@@ -87,9 +86,9 @@ STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_delay_us_obj, mcu_delay_us);
 
-//| .. function:: disable_interrupts()
-//|
-//|   Disable all interrupts. Be very careful, this can stall everything.
+//| def disable_interrupts() -> Any:
+//|     """Disable all interrupts. Be very careful, this can stall everything."""
+//|     ...
 //|
 STATIC mp_obj_t mcu_disable_interrupts(void) {
     common_hal_mcu_disable_interrupts();
@@ -97,9 +96,9 @@ STATIC mp_obj_t mcu_disable_interrupts(void) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_disable_interrupts_obj, mcu_disable_interrupts);
 
-//| .. function:: enable_interrupts()
-//|
-//|   Enable the interrupts that were enabled at the last disable.
+//| def enable_interrupts() -> Any:
+//|     """Enable the interrupts that were enabled at the last disable."""
+//|     ...
 //|
 STATIC mp_obj_t mcu_enable_interrupts(void) {
     common_hal_mcu_enable_interrupts();
@@ -107,12 +106,12 @@ STATIC mp_obj_t mcu_enable_interrupts(void) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_enable_interrupts_obj, mcu_enable_interrupts);
 
-//| .. function:: on_next_reset(run_mode)
+//| def on_next_reset(run_mode: microcontroller.RunMode) -> Any:
+//|     """Configure the run mode used the next time the microcontroller is reset but
+//|     not powered down.
 //|
-//|   Configure the run mode used the next time the microcontroller is reset but
-//|   not powered down.
-//|
-//|   :param ~microcontroller.RunMode run_mode: The next run mode
+//|     :param ~microcontroller.RunMode run_mode: The next run mode"""
+//|     ...
 //|
 STATIC mp_obj_t mcu_on_next_reset(mp_obj_t run_mode_obj) {
     mcu_runmode_t run_mode;
@@ -132,14 +131,14 @@ STATIC mp_obj_t mcu_on_next_reset(mp_obj_t run_mode_obj) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_on_next_reset_obj, mcu_on_next_reset);
 
-//| .. function:: reset()
-//|
-//|   Reset the microcontroller. After reset, the microcontroller will enter the
-//|   run mode last set by `on_next_reset`.
+//| def reset() -> Any:
+//|     """Reset the microcontroller. After reset, the microcontroller will enter the
+//|     run mode last set by `on_next_reset`.
 //|
-//|   .. warning:: This may result in file system corruption when connected to a
-//|     host computer. Be very careful when calling this! Make sure the device
-//|     "Safely removed" on Windows or "ejected" on Mac OSX and Linux.
+//|     .. warning:: This may result in file system corruption when connected to a
+//|       host computer. Be very careful when calling this! Make sure the device
+//|       "Safely removed" on Windows or "ejected" on Mac OSX and Linux."""
+//|     ...
 //|
 STATIC mp_obj_t mcu_reset(void) {
     common_hal_mcu_reset();
@@ -148,22 +147,21 @@ STATIC mp_obj_t mcu_reset(void) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_reset_obj, mcu_reset);
 
-//| .. data:: nvm
-//|
-//|   Available non-volatile memory.
-//|   This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise.
+//| nvm: Any = ...
+//| """Available non-volatile memory.
+//| This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise.
 //|
-//|   :type: nvm.ByteArray or None
+//| :type: nvm.ByteArray or None"""
 //|
 
-//| :mod:`microcontroller.pin` --- Microcontroller pin names
+//| """:mod:`microcontroller.pin` --- Microcontroller pin names
 //| --------------------------------------------------------
 //|
 //| .. module:: microcontroller.pin
 //|   :synopsis: Microcontroller pin names
 //|   :platform: SAMD21
 //|
-//| References to pins as named by the microcontroller
+//| References to pins as named by the microcontroller"""
 //|
 const mp_obj_module_t mcu_pin_module = {
     .base = { &mp_type_module },
diff --git a/shared-bindings/multiterminal/__init__.c b/shared-bindings/multiterminal/__init__.c
index 8de3c50d7..3a4065019 100644
--- a/shared-bindings/multiterminal/__init__.c
+++ b/shared-bindings/multiterminal/__init__.c
@@ -30,7 +30,7 @@
 #include "py/runtime.h"
 #include "supervisor/shared/translate.h"
 
-//| :mod:`multiterminal` --- Manage additional terminal sources
+//| """:mod:`multiterminal` --- Manage additional terminal sources
 //| ===========================================================
 //|
 //| .. module:: multiterminal
@@ -39,25 +39,25 @@
 //|
 //| The `multiterminal` module allows you to configure an additional serial
 //| terminal source. Incoming characters are accepted from both the internal
-//| serial connection and the optional secondary connection.
+//| serial connection and the optional secondary connection."""
 //|
 
-//|   .. function:: get_secondary_terminal()
-//|
-//|     Returns the current secondary terminal.
+//| def get_secondary_terminal() -> Any:
+//|     """Returns the current secondary terminal."""
+//|     ...
 //|
 STATIC mp_obj_t multiterminal_obj_get_secondary_terminal() {
     return common_hal_multiterminal_get_secondary_terminal();
 }
 MP_DEFINE_CONST_FUN_OBJ_0(multiterminal_get_secondary_terminal_obj, multiterminal_obj_get_secondary_terminal);
 
-//|   .. function:: set_secondary_terminal(stream)
-//|
-//|     Read additional input from the given stream and write out back to it.
+//| def set_secondary_terminal(stream: stream) -> Any:
+//|     """Read additional input from the given stream and write out back to it.
 //|     This doesn't replace the core stream (usually UART or native USB) but is
 //|     mixed in instead.
 //|
-//|     :param stream stream: secondary stream
+//|     :param stream stream: secondary stream"""
+//|     ...
 //|
 STATIC mp_obj_t multiterminal_obj_set_secondary_terminal(mp_obj_t secondary_terminal) {
     mp_obj_t write_m[3];
@@ -73,9 +73,9 @@ STATIC mp_obj_t multiterminal_obj_set_secondary_terminal(mp_obj_t secondary_term
 }
 MP_DEFINE_CONST_FUN_OBJ_1(multiterminal_set_secondary_terminal_obj, multiterminal_obj_set_secondary_terminal);
 
-//|   .. function:: clear_secondary_terminal()
-//|
-//|     Clears the secondary terminal.
+//| def clear_secondary_terminal() -> Any:
+//|     """Clears the secondary terminal."""
+//|     ...
 //|
 STATIC mp_obj_t multiterminal_obj_clear_secondary_terminal() {
     common_hal_multiterminal_clear_secondary_terminal();
@@ -83,11 +83,11 @@ STATIC mp_obj_t multiterminal_obj_clear_secondary_terminal() {
 }
 MP_DEFINE_CONST_FUN_OBJ_0(multiterminal_clear_secondary_terminal_obj, multiterminal_obj_clear_secondary_terminal);
 
-//|   .. function:: schedule_secondary_terminal_read(socket)
-//|
-//|     In cases where the underlying OS is doing task scheduling, this notifies
+//| def schedule_secondary_terminal_read(socket: Any) -> Any:
+//|     """In cases where the underlying OS is doing task scheduling, this notifies
 //|     the OS when more data is available on the socket to read. This is useful
-//|     as a callback for lwip sockets.
+//|     as a callback for lwip sockets."""
+//|     ...
 //|
 // TODO(tannewt): This is a funny API. Replace it with a direct call into the OS
 // by the lwip object.