From 7e55905d95abeb782ad9afb876bd1f4c40c75a07 Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Thu, 12 Aug 2021 11:15:04 -0700 Subject: [PATCH] Fix up onewireio docs and other notes Not all of the notes were marked correctly. --- shared-bindings/_bleio/Adapter.c | 4 ++-- shared-bindings/canio/__init__.c | 2 +- shared-bindings/keypad/EventQueue.c | 2 +- shared-bindings/onewireio/OneWire.c | 14 +++++--------- shared-bindings/onewireio/__init__.c | 4 +++- shared-bindings/traceback/__init__.c | 4 ++-- 6 files changed, 14 insertions(+), 16 deletions(-) diff --git a/shared-bindings/_bleio/Adapter.c b/shared-bindings/_bleio/Adapter.c index 8262830aee..c126ee79f2 100644 --- a/shared-bindings/_bleio/Adapter.c +++ b/shared-bindings/_bleio/Adapter.c @@ -197,10 +197,10 @@ const mp_obj_property_t bleio_adapter_name_obj = { //| """Starts advertising until `stop_advertising` is called or if connectable, another device //| connects to us. //| -//| .. warning: If data is longer than 31 bytes, then this will automatically advertise as an +//| .. warning:: If data is longer than 31 bytes, then this will automatically advertise as an //| extended advertisement that older BLE 4.x clients won't be able to scan for. //| -//| .. note: If you set ``anonymous=True``, then a timeout must be specified. If no timeout is +//| .. note:: If you set ``anonymous=True``, then a timeout must be specified. If no timeout is //| specified, then the maximum allowed timeout will be selected automatically. //| //| :param ~_typing.ReadableBuffer data: advertising data packet bytes diff --git a/shared-bindings/canio/__init__.c b/shared-bindings/canio/__init__.c index d9863e8a21..7f367ee791 100644 --- a/shared-bindings/canio/__init__.c +++ b/shared-bindings/canio/__init__.c @@ -80,7 +80,7 @@ MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, BUS_OFF, BUS_STATE_OFF); //| ERROR_WARNING: object //| """The bus is in the normal (active) state, but a moderate number of errors have occurred recently. //| -//| NOTE: Not all implementations may use ERROR_WARNING. Do not rely on seeing ERROR_WARNING before ERROR_PASSIVE.""" +//| .. note:: Not all implementations may use ``ERROR_WARNING``. Do not rely on seeing ``ERROR_WARNING`` before ``ERROR_PASSIVE``.""" //| //| ERROR_PASSIVE: object //| """The bus is in the passive state due to the number of errors that have occurred recently. diff --git a/shared-bindings/keypad/EventQueue.c b/shared-bindings/keypad/EventQueue.c index 15cc027b8c..2cb449551b 100644 --- a/shared-bindings/keypad/EventQueue.c +++ b/shared-bindings/keypad/EventQueue.c @@ -68,7 +68,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(keypad_eventqueue_get_obj, keypad_eventqueue_get); //| Note that the queue size is limited; see ``max_events`` in the constructor of //| a scanner such as `Keys` or `KeyMatrix`. //| -//| :return ``True`` if an event was available and stored, ``False`` if not. +//| :return: ``True`` if an event was available and stored, ``False`` if not. //| :rtype: bool //| """ //| ... diff --git a/shared-bindings/onewireio/OneWire.c b/shared-bindings/onewireio/OneWire.c index dd628884dd..406b421fd1 100644 --- a/shared-bindings/onewireio/OneWire.c +++ b/shared-bindings/onewireio/OneWire.c @@ -35,20 +35,16 @@ #include "shared-bindings/util.h" //| class OneWire: -//| """Lowest-level of the Maxim OneWire protocol""" -//| //| def __init__(self, pin: microcontroller.Pin) -> None: -//| """(formerly Dallas Semi) OneWire protocol. +//| """Create a OneWire object associated with the given pin. //| -//| Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126 -//| -//| .. class:: OneWire(pin) -//| -//| Create a OneWire object associated with the given pin. The object -//| implements the lowest level timing-sensitive bits of the protocol. +//| The object implements the lowest level timing-sensitive bits of the protocol. //| //| :param ~microcontroller.Pin pin: Pin connected to the OneWire bus //| +//| .. note:: The OneWire class is available on `busio` and `bitbangio` in CircuitPython +//| 7.x for backwards compatibility but will be removed in CircuitPython 8.0.0. +//| //| Read a short series of pulses:: //| //| import onewireio diff --git a/shared-bindings/onewireio/__init__.c b/shared-bindings/onewireio/__init__.c index 4074891be9..81baa99fab 100644 --- a/shared-bindings/onewireio/__init__.c +++ b/shared-bindings/onewireio/__init__.c @@ -35,7 +35,9 @@ #include "py/runtime.h" -//| """Low-level bit primitives for """ +//| """Low-level bit primitives for Maxim (formerly Dallas Semi) one-wire protocol. +//| +//| Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126""" //| STATIC const mp_rom_map_elem_t onewireio_module_globals_table[] = { diff --git a/shared-bindings/traceback/__init__.c b/shared-bindings/traceback/__init__.c index dc5be20a88..c12175f89b 100644 --- a/shared-bindings/traceback/__init__.c +++ b/shared-bindings/traceback/__init__.c @@ -73,7 +73,7 @@ STATIC void traceback_exception_common(mp_print_t *print, mp_obj_t value, mp_obj //| these lines are concatenated and printed, exactly the same text is //| printed as does print_exception(). //| -//| .. note: Setting `chain` will have no effect as chained exceptions are not yet implemented. +//| .. note:: Setting ``chain`` will have no effect as chained exceptions are not yet implemented. //| //| :param Type[BaseException] etype: This is ignored and inferred from the type of ``value``. //| :param BaseException value: The exception. Must be an instance of `BaseException`. @@ -112,7 +112,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(traceback_format_exception_obj, 3, traceback_f //| //| """Prints exception information and stack trace entries. //| -//| .. note: Setting `chain` will have no effect as chained exceptions are not yet implemented. +//| .. note:: Setting ``chain`` will have no effect as chained exceptions are not yet implemented. //| //| :param Type[BaseException] etype: This is ignored and inferred from the type of ``value``. //| :param BaseException value: The exception. Must be an instance of `BaseException`.