Merge pull request #7097 from dhalbert/document-limitations

catalog implementation limitations in documentation

Author: kattni

shared-bindings/alarm/SleepMemory.c

@@ -42,6 +42,8 @@
 //|     instance of :class:`SleepMemory` is available at
 //|     :attr:`alarm.sleep_memory`.
 //|
+//|     **Limitations:** Not supported on RP2040.
+//|
 //|     Usage::
 //|
 //|        import alarm

shared-bindings/alarm/__init__.c

@@ -146,6 +146,8 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(alarm_light_sleep_until_alarms_obj, 1, MP_OB
 //|
 //|     On some microcontrollers, some pins cannot remain in their original state for hardware reasons.
 //|
+//|     **Limitations:** ``preserve_dios`` is currently only available on Espressif.
+//|
 //|     .. note::
 //|       On Espressif chips, preserving pin settings during deep sleep may consume extra current.
 //|       On ESP32, this was measured to be 250 uA or more.

shared-bindings/alarm/touch/TouchAlarm.c

@@ -39,6 +39,8 @@
 //|
 //|         :param microcontroller.Pin pin: The pin to monitor. On some ports, the choice of pin
 //|           may be limited due to hardware restrictions, particularly for deep-sleep alarms.
+//|
+//|         **Limitations:** Not available on SAMD, nRF, or RP2040.
 //|         """
 //|         ...
 STATIC mp_obj_t alarm_touch_touchalarm_make_new(const mp_obj_type_t *type,

shared-bindings/analogio/AnalogOut.c

@@ -50,7 +50,11 @@
 //|     def __init__(self, pin: microcontroller.Pin) -> None:
 //|         """Use the AnalogOut on the given pin.
 //|
-//|         :param ~microcontroller.Pin pin: the pin to output to"""
+//|         :param ~microcontroller.Pin pin: the pin to output to
+//|
+//|         **Limitations:** Not available on nRF, RP2040, Spresense: there is no on-chip DAC.
+//|          Espressif: available only on ESP32 and ESP32-S2; other chips do not have a DAC.
+//|         """
 //|         ...
 STATIC mp_obj_t analogio_analogout_make_new(const mp_obj_type_t *type, mp_uint_t n_args, size_t n_kw, const mp_obj_t *args) {
     // check arguments

shared-bindings/audiobusio/PDMIn.c

@@ -65,31 +65,32 @@
 //|         :param int oversample: Number of single bit samples to decimate into a final sample. Must be divisible by 8
 //|         :param float startup_delay: seconds to wait after starting microphone clock
 //|          to allow microphone to turn on. Most require only 0.01s; some require 0.1s. Longer is safer.
-//|          Must be in range 0.0-1.0 seconds."""
-
-//|     """Record 8-bit unsigned samples to buffer::
+//|          Must be in range 0.0-1.0 seconds.
+//|
+//|         **Limitations:** On SAMD and RP2040, supports only 8 or 16 bit mono input, with 64x oversampling.
+//|         On nRF52840, supports only 16 bit mono input at 16 kHz; oversampling is fixed at 64x. Not provided
+//|         on nRF52833 for space reasons. Not available on Espressif.
+//|
+//|         For example, to record 8-bit unsigned samples to a buffer::
 //|
-//|       import audiobusio
-//|       import board
+//|           import audiobusio
+//|           import board
 //|
-//|       # Prep a buffer to record into
-//|       b = bytearray(200)
-//|       with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000) as mic:
-//|           mic.record(b, len(b))
+//|           # Prep a buffer to record into
+//|           b = bytearray(200)
+//|           with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000) as mic:
+//|               mic.record(b, len(b))
 //|
-//|     Record 16-bit unsigned samples to buffer::
+//|         To record 16-bit unsigned samples to a buffer::
 //|
-//|       import audiobusio
-//|       import board
+//|           import audiobusio
+//|           import board
 //|
-//|       # Prep a buffer to record into. The array interface doesn't allow for
-//|       # constructing with a set size so we append to it until we have the size
-//|       # we want.
-//|       b = array.array("H")
-//|       for i in range(200):
-//|           b.append(0)
-//|       with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000, bit_depth=16) as mic:
-//|           mic.record(b, len(b))"""
+//|           # Prep a buffer to record into.
+//|           b = array.array("H", [0] * 200)
+//|           with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000, bit_depth=16) as mic:
+//|               mic.record(b, len(b))
+//|         """
 //|     ...
 STATIC mp_obj_t audiobusio_pdmin_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) {
     #if !CIRCUITPY_AUDIOBUSIO_PDMIN

shared-bindings/busio/SPI.c

@@ -81,7 +81,10 @@
 //|         :param ~microcontroller.Pin clock: the pin to use for the clock.
 //|         :param ~microcontroller.Pin MOSI: the Main Out Selected In pin.
 //|         :param ~microcontroller.Pin MISO: the Main In Selected Out pin.
-//|         :param bool half_duplex: True when MOSI is used for bidirectional data. False when SPI is full-duplex or simplex."""
+//|         :param bool half_duplex: True when MOSI is used for bidirectional data. False when SPI is full-duplex or simplex.
+//|
+//|         **Limitations:** ``half_duplex`` is available only on STM; other chips do not have the hardware support.
+//|         """
 //|         ...
 
 

shared-bindings/busio/UART.c

@@ -77,9 +77,10 @@
 //|         *New in CircuitPython 4.0:* ``timeout`` has incompatibly changed units from milliseconds to seconds.
 //|         The new upper limit on ``timeout`` is meant to catch mistaken use of milliseconds.
 //|
-//|         .. note:: RS485 support on i.MX and Raspberry Pi RP2040 is implemented in software.
-//|            The timing for the ``rs485_dir`` pin signal is done on a best-effort basis, and may not meet
-//|            RS485 specifications intermittently.
+//|         **Limitations:** RS485 is not supported on SAMD, nRF, Broadcom, Spresense, or STM.
+//|         On i.MX and Raspberry Pi RP2040 support is implemented in software:
+//|         The timing for the ``rs485_dir`` pin signal is done on a best-effort basis, and may not meet
+//|         RS485 specifications intermittently.
 //|         """
 //|         ...
 typedef struct {

shared-bindings/countio/Edge.c

@@ -47,7 +47,10 @@ MAKE_ENUM_VALUE(countio_edge_type, edge, RISE_AND_FALL, EDGE_RISE_AND_FALL);
 //|     """Count the falling edges."""
 //|
 //|     RISE_AND_FALL: Edge
-//|     """Count the rising and falling edges."""
+//|     """Count the rising and falling edges.
+//|
+//|     **Limitations:** ``RISE_AND_FALL`` is not available to RP2040 due to hardware limitations.
+//|     """
 //|
 MAKE_ENUM_MAP(countio_edge) {
     MAKE_ENUM_MAP_ENTRY(edge, RISE),

shared-bindings/microcontroller/Processor.c

@@ -106,7 +106,7 @@ MP_PROPERTY_GETTER(mcu_processor_reset_reason_obj,
 //|
 //|     Is `None` if the temperature is not available.
 //|
-//|     .. note :: On small SAMD21 builds without external flash,
+//|     **Limitations:** Not available on ESP32 or ESP32-S3. On small SAMD21 builds without external flash,
 //|       the reported temperature has reduced accuracy and precision, to save code space.
 //|     """
 STATIC mp_obj_t mcu_processor_get_temperature(mp_obj_t self) {

shared-bindings/os/__init__.c

@@ -235,7 +235,10 @@ MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync);
 
 //| def urandom(size: int) -> str:
 //|     """Returns a string of *size* random bytes based on a hardware True Random
-//|     Number Generator. When not available, it will raise a NotImplementedError."""
+//|     Number Generator. When not available, it will raise a NotImplementedError.
+//|
+//|     **Limitations:** Not yet available on nRF. Not available on SAMD21 due to lack of hardware.
+//|     """
 //|     ...
 //|
 STATIC mp_obj_t os_urandom(mp_obj_t size_in) {