From edf507e57d2a85ef80049a8d7e1a56c7eb193607 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Fri, 21 Mar 2025 14:30:06 -0400 Subject: [PATCH] Multiple documentation fixes --- docs/library/errno.rst | 2 +- shared-bindings/_stage/__init__.c | 4 ++-- shared-bindings/aesio/aes.c | 6 ++++-- shared-bindings/alarm/time/TimeAlarm.c | 6 ++++++ shared-bindings/analogio/AnalogOut.c | 3 +++ shared-bindings/busio/I2C.c | 3 +++ shared-bindings/busio/SPI.c | 4 +++- shared-bindings/epaperdisplay/EPaperDisplay.c | 3 ++- shared-bindings/fourwire/FourWire.c | 6 +++++- shared-bindings/i2cdisplaybus/I2CDisplayBus.c | 6 +++++- shared-bindings/index.rst | 6 ++++++ shared-bindings/paralleldisplaybus/ParallelBus.c | 6 +++++- shared-bindings/rotaryio/IncrementalEncoder.c | 8 +++++++- shared-bindings/synthio/LFO.c | 2 +- 14 files changed, 53 insertions(+), 12 deletions(-) diff --git a/docs/library/errno.rst b/docs/library/errno.rst index 61970291df57a..10ecd4d2c791d 100644 --- a/docs/library/errno.rst +++ b/docs/library/errno.rst @@ -7,7 +7,7 @@ |see_cpython_module| :mod:`python:errno`. This module provides access to symbolic error codes for `OSError` exception. -The codes available may vary per CircuitPython build. +Some codes are not available on the smallest CircuitPython builds, such as SAMD21, for space reasons. Constants --------- diff --git a/shared-bindings/_stage/__init__.c b/shared-bindings/_stage/__init__.c index 7542941a4f5e4..bd5e89b5a67ab 100644 --- a/shared-bindings/_stage/__init__.c +++ b/shared-bindings/_stage/__init__.c @@ -16,8 +16,8 @@ //| """C-level helpers for animation of sprites on a stage //| -//| The `_stage` module contains native code to speed-up the ```stage`` Library -//| `_.""" +//| The `_stage` module contains native code to speed-up the ``stage`` +//| `library `_.""" //| //| //| def render( diff --git a/shared-bindings/aesio/aes.c b/shared-bindings/aesio/aes.c index be0935aac9e09..a6916042fda19 100644 --- a/shared-bindings/aesio/aes.c +++ b/shared-bindings/aesio/aes.c @@ -177,8 +177,10 @@ static void validate_length(aesio_aes_obj_t *self, size_t src_length, //| """Encrypt the buffer from ``src`` into ``dest``. //| //| For ECB mode, the buffers must be 16 bytes long. For CBC mode, the -//| buffers must be a multiple of 16 bytes, and must be equal length. For -//| CTR mode, there are no restrictions.""" +//| buffers must be a multiple of 16 bytes, and must be equal length. +//| Any included padding must conform to the required padding style for the given mode. +//| For CTR mode, there are no restrictions. +//| """ //| ... //| static mp_obj_t aesio_aes_encrypt_into(mp_obj_t self_in, mp_obj_t src, mp_obj_t dest) { diff --git a/shared-bindings/alarm/time/TimeAlarm.c b/shared-bindings/alarm/time/TimeAlarm.c index a40e8dd08e6ae..0277c22fc44bf 100644 --- a/shared-bindings/alarm/time/TimeAlarm.c +++ b/shared-bindings/alarm/time/TimeAlarm.c @@ -35,6 +35,12 @@ mp_obj_t MP_WEAK rtc_get_time_source_time(void) { //| If the given time is already in the past, then an exception is raised. //| If the sleep happens after the given time, then it will wake immediately //| due to this time alarm. +//| +//| Example:: +//| +//| # Deep sleep for 30 seconds. +//| time_alarm = alarm.time.TimeAlarm(monotonic_time=time.monotonic() + 30) +//| alarm.exit_and_deep_sleep_until_alarms(time_alarm) //| """ //| ... //| diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index 15fe1657c8714..b9e5824f978b7 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -20,6 +20,9 @@ //| //| **Limitations:** Not available on Nordic, RP2040, Spresense, as there is no on-chip DAC. //| On Espressif, available only on ESP32 and ESP32-S2; other chips do not have a DAC. +//| On ESP32-S2 boards, GPIO18 (DAC2) is often connected to a pull-up resistor, which causes +//| `unexpected output values in the lower part of the output range +//| `_. //| //| Example usage:: //| diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index 1b26a5659abc1..8aa35ec6e0709 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -39,6 +39,9 @@ //| bit unpacking. Instead, use an existing driver or make one with //| :ref:`Register ` data descriptors. //| +//| .. seealso:: This class provides an I2C controller, which controls I2C targets (peripherals). +//| To act as an I2C target, use `i2ctarget.I2CTarget`. +//| //| :param ~microcontroller.Pin scl: The clock pin //| :param ~microcontroller.Pin sda: The data pin //| :param int frequency: The clock frequency in Hertz diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 9fcfc0e87a0ff..0c8ae1bfdd72c 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -28,7 +28,7 @@ //| main device. It is typically faster than :py:class:`~bitbangio.I2C` because a //| separate pin is used to select a device rather than a transmitted //| address. This class only manages three of the four SPI lines: `!clock`, -//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate +//| `!MOSI`, `!MISO`. It is up to the client to manage the appropriate //| select line, often abbreviated `!CS` or `!SS`. (This is common because //| multiple secondaries can share the `!clock`, `!MOSI` and `!MISO` lines //| and therefore the hardware.) @@ -46,6 +46,8 @@ //| //|

//| +//| .. seealso:: This class acts as an SPI main (controller). +//| To act as an SPI secondary (target), use `spitarget.SPITarget`. //| """ //| //| def __init__( diff --git a/shared-bindings/epaperdisplay/EPaperDisplay.c b/shared-bindings/epaperdisplay/EPaperDisplay.c index 10291b7d99fde..0d558a1319616 100644 --- a/shared-bindings/epaperdisplay/EPaperDisplay.c +++ b/shared-bindings/epaperdisplay/EPaperDisplay.c @@ -29,7 +29,8 @@ //| is called. This is done so that CircuitPython can use the display itself. //| //| Most people should not use this class directly. Use a specific display driver instead that will -//| contain the startup and shutdown sequences at minimum.""" +//| contain the startup and shutdown sequences at minimum. +//| """ //| //| def __init__( //| self, diff --git a/shared-bindings/fourwire/FourWire.c b/shared-bindings/fourwire/FourWire.c index 4b08c00566f44..083cf21a00367 100644 --- a/shared-bindings/fourwire/FourWire.c +++ b/shared-bindings/fourwire/FourWire.c @@ -20,7 +20,11 @@ //| class FourWire: //| """Manage updating a display over SPI four wire protocol in the background while Python code runs. -//| It doesn't handle display initialization.""" +//| It doesn't handle display initialization. +//| +//| .. seealso:: See `busdisplay.BusDisplay` and `epaperdisplay.EPaperDisplay` +//| for how to initialize a display, given a `FourWire` bus. +//| """ //| //| def __init__( //| self, diff --git a/shared-bindings/i2cdisplaybus/I2CDisplayBus.c b/shared-bindings/i2cdisplaybus/I2CDisplayBus.c index d6e0763052b2d..8633f166805d2 100644 --- a/shared-bindings/i2cdisplaybus/I2CDisplayBus.c +++ b/shared-bindings/i2cdisplaybus/I2CDisplayBus.c @@ -19,7 +19,11 @@ //| class I2CDisplayBus: //| """Manage updating a display over I2C in the background while Python code runs. -//| It doesn't handle display initialization.""" +//| It doesn't handle display initialization. +//| +//| .. seealso:: See `busdisplay.BusDisplay` and `epaperdisplay.EPaperDisplay` +//| for how to initialize a display, given an `I2CDisplayBus`. +//| """ //| //| def __init__( //| self, diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst index bf04ae18b1338..6d3e4d6884209 100644 --- a/shared-bindings/index.rst +++ b/shared-bindings/index.rst @@ -15,6 +15,12 @@ a list of modules supported on each board. Modules --------- +.. note:: Some modules are documented in :doc:`/docs/library/index`, not here: + `builtins`, `heapq`, `array`, `binascii`, `collections`, `errno`, `gc`, + `io`, `json`, `re`, `sys`, `select`. + + The documentation for :func:`help` is at the end of this page. + .. toctree:: :glob: :maxdepth: 2 diff --git a/shared-bindings/paralleldisplaybus/ParallelBus.c b/shared-bindings/paralleldisplaybus/ParallelBus.c index 1e0bd63674422..dfe363bdcb797 100644 --- a/shared-bindings/paralleldisplaybus/ParallelBus.c +++ b/shared-bindings/paralleldisplaybus/ParallelBus.c @@ -18,7 +18,11 @@ //| class ParallelBus: //| """Manage updating a display over 8-bit parallel bus in the background while Python code runs. This //| protocol may be referred to as 8080-I Series Parallel Interface in datasheets. It doesn't handle -//| display initialization.""" +//| display initialization. +//| +//| .. seealso:: See `busdisplay.BusDisplay` and `epaperdisplay.EPaperDisplay` +//| for how to initialize a display, given a `ParallelBus`. +//| """ //| //| def __init__( //| self, diff --git a/shared-bindings/rotaryio/IncrementalEncoder.c b/shared-bindings/rotaryio/IncrementalEncoder.c index 810782bc526f6..0cd94c0756214 100644 --- a/shared-bindings/rotaryio/IncrementalEncoder.c +++ b/shared-bindings/rotaryio/IncrementalEncoder.c @@ -42,7 +42,13 @@ //| position = enc.position //| if last_position == None or position != last_position: //| print(position) -//| last_position = position""" +//| last_position = position +//| +//| .. warning:: On RP2350 boards, any pulldowns used must be 8.2 kohms or less, +//| to overcome a hardware issue. +//| See the RP2350 warning in `digitalio` for more information. +//| """ +//| //| ... //| static mp_obj_t rotaryio_incrementalencoder_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) { diff --git a/shared-bindings/synthio/LFO.c b/shared-bindings/synthio/LFO.c index c1935f9e96d89..ee2d67d308903 100644 --- a/shared-bindings/synthio/LFO.c +++ b/shared-bindings/synthio/LFO.c @@ -43,7 +43,7 @@ static const uint16_t triangle[] = {0, 32767, 0, -32767}; //| An LFO's ``value`` property is computed once when it is constructed, and then //| when its associated synthesizer updates it. //| -//| This means that for instance an LFO **created** with ``offset=1`` has ```value==1`` +//| This means that for instance an LFO **created** with ``offset=1`` has ``value==1`` //| immediately, but **updating** the ``offset`` property alone does not //| change ``value``; it only updates through an association with an active synthesizer. //|