Merge pull request #4 from adafruit/master

merge from adafruit

4 files changed, 80 insertions, 114 deletions

diff --git a/shared-bindings/microcontroller/Pin.c b/shared-bindings/microcontroller/Pin.c
index 67aecaf66..765e602e5 100644
--- a/shared-bindings/microcontroller/Pin.c
+++ b/shared-bindings/microcontroller/Pin.c
@@ -33,18 +33,14 @@
 #include "py/runtime.h"
 #include "supervisor/shared/translate.h"
 
-//| .. currentmodule:: microcontroller
+//| class Pin:
+//|     """Identifies an IO pin on the microcontroller."""
 //|
-//| :class:`Pin` --- Pin reference
-//| ------------------------------------------
-//|
-//| 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..c4b249124 100644
--- a/shared-bindings/microcontroller/Processor.c
+++ b/shared-bindings/microcontroller/Processor.c
@@ -34,29 +34,24 @@
 
 #include "py/runtime.h"
 
-//| .. currentmodule:: microcontroller
+//| class Processor:
+//|     """Microcontroller CPU information and control
 //|
-//| :class:`Processor` --- Microcontroller CPU information and control
-//| ------------------------------------------------------------------
+//|     Usage::
 //|
-//| Get information about the microcontroller CPU and control it.
-//|
-//| 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: int = ...
+//|     """The CPU operating frequency 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 +67,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 +87,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 +106,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..6db315d8d 100644
--- a/shared-bindings/microcontroller/RunMode.c
+++ b/shared-bindings/microcontroller/RunMode.c
@@ -26,34 +26,28 @@
 
 #include "shared-bindings/microcontroller/RunMode.h"
 
-//| .. currentmodule:: microcontroller
+//| class RunMode:
+//|     """run state of the microcontroller"""
 //|
-//| :class:`RunMode` -- run state of the microcontroller
-//| =============================================================
+//|     def __init__(self, ):
+//|         """Enum-like class to define the run mode of the microcontroller and
+//|         CircuitPython."""
 //|
-//| .. class:: RunMode()
+//|     NORMAL: Any = ...
+//|     """Run CircuitPython as normal.
 //|
-//|     Enum-like class to define the run mode of the microcontroller and
-//|     CircuitPython.
+//|     :type microcontroller.RunMode:"""
 //|
-//|     .. attribute:: NORMAL
+//|     SAFE_MODE: Any = ...
+//|     """Run CircuitPython in safe mode. User code will not be run and the
+//|     file system will be writeable over USB.
 //|
-//|       Run CircuitPython as normal.
+//|     :type microcontroller.RunMode:"""
 //|
-//|       :type microcontroller.RunMode:
+//|     BOOTLOADER: Any = ...
+//|     """Run the bootloader.
 //|
-//|     .. attribute:: SAFE_MODE
-//|
-//|       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..21e1c90a9 100644
--- a/shared-bindings/microcontroller/__init__.c
+++ b/shared-bindings/microcontroller/__init__.c
@@ -42,41 +42,26 @@
 #include "py/runtime.h"
 #include "supervisor/shared/translate.h"
 
-//| :mod:`microcontroller` --- Pin references and cpu functionality
-//| ================================================================
-//|
-//| .. module:: microcontroller
-//|   :synopsis: Pin references and core functionality
-//|   :platform: SAMD21, ESP8266
+//| """Pin references and cpu functionality
 //|
 //| The `microcontroller` module defines the pins from the perspective of the
-//| microcontroller. See `board` for board-specific pin mappings.
-//|
-//| Libraries
-//|
-//| .. toctree::
-//|     :maxdepth: 3
-//|
-//|     Pin
-//|     Processor
-//|     RunMode
+//| microcontroller. See `board` for board-specific pin mappings."""
 //|
 
-//| .. 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: Processor = ...
+//| """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 +72,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 +82,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 +92,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)
-//|
-//|   Configure the run mode used the next time the microcontroller is reset but
-//|   not powered down.
+//| 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.
 //|
-//|   :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 +117,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 +133,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 },