Merge pull request micropython#10160 from dhalbert/9.2.x-doc-fixes

dhalbert · web-flow · commit ae285da1e867 · 2025-03-21T15:43:14.000-04:00
Fix multiple documentation issues.
diff --git 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
@@ -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
-//| <https://github.com/python-ugame/circuitpython-stage>`_."""
+//| The `_stage` module contains native code to speed-up the ``stage``
+//| `library <https://github.com/python-ugame/circuitpython-stage>`_."""
 //|
 //|
 //| def render(
diff --git 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
@@ -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
@@ -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
+//|     <https://github.com/adafruit/circuitpython/issues/7871>`_.
 //|
 //|     Example usage::
 //|
diff --git 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 <register-module-reference>` 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
@@ -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 @@
 //|         </details>
 //|         </p>
 //|
+//|     .. 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
 //|
