diff --git a/shared-bindings/math/__init__.c b/shared-bindings/math/__init__.c index 0bf8047c98..755bf75897 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) + //| def acos(x: Any) -> Any: + //| """Return the inverse cosine of ``x``.""" + //| ... //| - //| Return the inverse cosine of ``x``. + //| def asin(x: Any) -> Any: + //| """Return the inverse sine of ``x``.""" + //| ... //| - //| .. function:: asin(x) + //| def atan(x: Any) -> Any: + //| """Return the inverse tangent of ``x``.""" + //| ... //| - //| Return the inverse sine of ``x``. + //| def atan2(y: Any, x: Any) -> Any: + //| """Return the principal value of the inverse tangent of ``y/x``.""" + //| ... //| - //| .. function:: atan(x) + //| def ceil(x: Any) -> Any: + //| """Return an integer, being ``x`` rounded towards positive infinity.""" + //| ... //| - //| Return the inverse tangent of ``x``. + //| def copysign(x: Any, y: Any) -> Any: + //| """Return ``x`` with the sign of ``y``.""" + //| ... //| - //| .. function:: atan2(y,x) + //| def cos(x: Any) -> Any: + //| """Return the cosine of ``x``.""" + //| ... //| - //| Return the principal value of the inverse tangent of ``y/x``. + //| def degrees(x: Any) -> Any: + //| """Return radians ``x`` converted to degrees.""" + //| ... //| - //| .. function:: ceil(x) + //| def exp(x: Any) -> Any: + //| """Return the exponential of ``x``.""" + //| ... //| - //| Return an integer, being ``x`` rounded towards positive infinity. + //| def fabs(x: Any) -> Any: + //| """Return the absolute value of ``x``.""" + //| ... //| - //| .. function:: copysign(x,y) + //| def floor(x: Any) -> Any: + //| """Return an integer, being ``x`` rounded towards negative infinity.""" + //| ... //| - //| Return ``x`` with the sign of ``y``. + //| def fmod(x: Any, y: Any) -> Any: + //| """Return the remainder of ``x/y``.""" + //| ... //| - //| .. function:: cos(x) + //| 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.""" + //| ... //| - //| Return the cosine of ``x``. + //| def isfinite(x: Any) -> Any: + //| """Return ``True`` if ``x`` is finite.""" + //| ... //| - //| .. function:: degrees(x) + //| def isinf(x: Any) -> Any: + //| """Return ``True`` if ``x`` is infinite.""" + //| ... //| - //| Return radians ``x`` converted to degrees. + //| def isnan(x: Any) -> Any: + //| """Return ``True`` if ``x`` is not-a-number""" + //| ... //| - //| .. function:: exp(x) + //| def ldexp(x: Any, exp: Any) -> Any: + //| """Return ``x * (2**exp)``.""" + //| ... //| - //| Return the exponential 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:: fabs(x) + //| def pow(x: Any, y: Any) -> Any: + //| """Returns ``x`` to the power of ``y``.""" //| - //| Return the absolute value of ``x``. + //| def radians(x: Any) -> Any: + //| """Return degrees ``x`` converted to radians.""" //| - //| .. function:: floor(x) + //| def sin(x: Any) -> Any: + //| """Return the sine of ``x``.""" + //| ... //| - //| Return an integer, being ``x`` rounded towards negative infinity. + //| def sqrt(x: Any) -> Any: + //| """Returns the square root of ``x``.""" + //| ... //| - //| .. function:: fmod(x,y) + //| def tan(x: Any) -> Any: ... + //| """Return the tangent of ``x``.""" + //| ... //| - //| Return the remainder of ``x/y``. - //| - //| .. function:: frexp(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. - //| - //| .. function:: isfinite(x) - //| - //| Return ``True`` if ``x`` is finite. - //| - //| .. function:: isinf(x) - //| - //| Return ``True`` if ``x`` is infinite. - //| - //| .. function:: isnan(x) - //| - //| Return ``True`` if ``x`` is not-a-number - //| - //| .. function:: ldexp(x, exp) - //| - //| Return ``x * (2**exp)``. - //| - //| .. function:: modf(x) - //| - //| Return a tuple of two floats, being the fractional and integral parts of - //| ``x``. Both return values have the same sign as ``x``. - //| - //| .. function:: pow(x, y) - //| - //| Returns ``x`` to the power of ``y``. - //| - //| .. function:: radians(x) - //| - //| Return degrees ``x`` converted to radians. - //| - //| .. function:: sin(x) - //| - //| Return the sine of ``x``. - //| - //| .. function:: sqrt(x) - //| - //| Returns the square root of ``x``. - //| - //| .. function:: tan(x) - //| - //| Return the tangent of ``x``. - //| - //| .. function:: trunc(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 67aecaf66e..cad0d67b1d 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 023f063e02..dedb5a27c2 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 +//| temperature: Any = ... +//| """The on-chip temperature, in Celsius, as a float. (read-only) //| -//| 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 +//| voltage: Any = ... +//| """The input voltage to the microcontroller, as a float. (read-only) //| -//| 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 913242ad26..df3ff41868 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 090c4564da..75b7639808 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() +//| def reset() -> Any: +//| """Reset the microcontroller. After reset, the microcontroller will enter the +//| run mode last set by `on_next_reset`. //| -//| 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 +//| nvm: Any = ... +//| """Available non-volatile memory. +//| This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise. //| -//| 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 8de3c50d7b..3a40650191 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.