Modify some Python stubs

Author: ciscorn

docs/autoapi/templates/python/module.rst

@@ -18,8 +18,7 @@
 {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
 {% if visible_subpackages %}
 .. toctree::
-   :titlesonly:
-   :maxdepth: 3
+   :maxdepth: 2
 
 {% for subpackage in visible_subpackages %}
    {{ subpackage.short_name }}/index.rst

shared-bindings/_bleio/Adapter.c

@@ -145,8 +145,8 @@ const mp_obj_property_t bleio_adapter_name_obj = {
 //|         .. 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 buf data: advertising data packet bytes
-//|         :param buf scan_response: scan response data packet bytes. ``None`` if no scan response is needed.
+//|         :param ~_typing.ReadableBuffer data: advertising data packet bytes
+//|         :param ~_typing.ReadableBuffer scan_response: scan response data packet bytes. ``None`` if no scan response is needed.
 //|         :param bool connectable:  If `True` then other devices are allowed to connect to this peripheral.
 //|         :param bool anonymous:  If `True` then this device's MAC address is randomized before advertising.
 //|         :param int timeout:  If set, we will only advertise for this many seconds.
@@ -219,7 +219,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_adapter_stop_advertising_obj, bleio_adapt
 //|         """Starts a BLE scan and returns an iterator of results. Advertisements and scan responses are
 //|         filtered and returned separately.
 //|
-//|         :param sequence prefixes: Sequence of byte string prefixes to filter advertising packets
+//|         :param ~_typing.ReadableBuffer prefixes: Sequence of byte string prefixes to filter advertising packets
 //|             with. A packet without an advertising structure that matches one of the prefixes is
 //|             ignored. Format is one byte for length (n) and n bytes of prefix and can be repeated.
 //|         :param int buffer_size: the maximum number of advertising bytes to buffer.
@@ -334,7 +334,7 @@ const mp_obj_property_t bleio_adapter_connected_obj = {
                (mp_obj_t)&mp_const_none_obj },
 };
 
-//|     connections: tuple
+//|     connections: Tuple[Connection]
 //|     """Tuple of active connections including those initiated through
 //|     :py:meth:`_bleio.Adapter.connect`. (read-only)"""
 //|

shared-bindings/_bleio/Address.c

@@ -42,7 +42,7 @@
 //|         """Create a new Address object encapsulating the address value.
 //|         The value itself can be one of:
 //|
-//|         :param buf address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes.
+//|         :param ~_typing.ReadableBuffer address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes.
 //|         :param int address_type: one of the integer values: `PUBLIC`, `RANDOM_STATIC`,
 //|           `RANDOM_PRIVATE_RESOLVABLE`, or `RANDOM_PRIVATE_NON_RESOLVABLE`."""
 //|         ...
@@ -128,7 +128,7 @@ const mp_obj_property_t bleio_address_type_obj = {
               (mp_obj_t)&mp_const_none_obj},
 };
 
-//|     def __eq__(self, other: Address) -> bool:
+//|     def __eq__(self, other: object) -> bool:
 //|         """Two Address objects are equal if their addresses and address types are equal."""
 //|         ...
 //|

shared-bindings/_bleio/Characteristic.c

@@ -63,7 +63,7 @@
 //|          is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum
 //|          number of data bytes that fit in a single BLE 4.x ATT packet.
 //|         :param bool fixed_length: True if the characteristic value is of fixed length.
-//|         :param buf initial_value: The initial value for this characteristic. If not given, will be
+//|         :param ~_typing.ReadableBuffer initial_value: The initial value for this characteristic. If not given, will be
 //|          filled with zeros.
 //|
 //|         :return: the new Characteristic."""

shared-bindings/_bleio/Connection.c

@@ -111,12 +111,12 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_connection_pair_obj, 1, bleio_connection
 
 //|     def discover_remote_services(self, service_uuids_whitelist: Optional[Iterable[UUID]] = None) -> Tuple[Service, ...]:
 //|         """Do BLE discovery for all services or for the given service UUIDS,
-//|          to find their handles and characteristics, and return the discovered services.
-//|          `Connection.connected` must be True.
+//|         to find their handles and characteristics, and return the discovered services.
+//|         `Connection.connected` must be True.
 //|
 //|         :param iterable service_uuids_whitelist:
 //|
-//|           an iterable of :py:class:~`UUID` objects for the services provided by the peripheral
+//|           an iterable of :py:class:`UUID` objects for the services provided by the peripheral
 //|           that you want to use.
 //|
 //|           The peripheral may provide more services, but services not listed are ignored
@@ -126,7 +126,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_connection_pair_obj, 1, bleio_connection
 //|           slow.
 //|
 //|           If the service UUID is 128-bit, or its characteristic UUID's are 128-bit, you
-//|           you must have already created a :py:class:~`UUID` object for that UUID in order for the
+//|           you must have already created a :py:class:`UUID` object for that UUID in order for the
 //|           service or characteristic to be discovered. Creating the UUID causes the UUID to be
 //|           registered for use. (This restriction may be lifted in the future.)
 //|

shared-bindings/_bleio/Descriptor.c

@@ -46,7 +46,7 @@
 //|         as part of remote Characteristics in the remote Services that are discovered."""
 //|
 //|     @classmethod
-//|     def add_to_characteristic(characteristic: Characteristic, uuid: UUID, *, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length = 20, fixed_length: bool = False, initial_value: ReadableBuffer = b'') -> Descriptor:
+//|     def add_to_characteristic(cls, characteristic: Characteristic, uuid: UUID, *, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int = 20, fixed_length: bool = False, initial_value: ReadableBuffer = b'') -> Descriptor:
 //|         """Create a new Descriptor object, and add it to this Service.
 //|
 //|         :param Characteristic characteristic: The characteristic that will hold this descriptor
@@ -61,7 +61,7 @@
 //|            is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum
 //|            number of data bytes that fit in a single BLE 4.x ATT packet.
 //|         :param bool fixed_length: True if the descriptor value is of fixed length.
-//|         :param buf initial_value: The initial value for this descriptor.
+//|         :param ~_typing.ReadableBuffer initial_value: The initial value for this descriptor.
 //|
 //|         :return: the new Descriptor."""
 //|         ...

shared-bindings/_bleio/UUID.c

@@ -48,7 +48,7 @@
 //|         temporary 16-bit UUID that can be used in place of the full 128-bit UUID.
 //|
 //|         :param value: The uuid value to encapsulate
-//|         :type value: int or typing.ByteString"""
+//|         :type value: int, ~_typing.ReadableBuffer or str"""
 //|         ...
 //|
 STATIC mp_obj_t bleio_uuid_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -248,7 +248,7 @@ STATIC mp_obj_t bleio_uuid_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
     }
 }
 
-//|     def __eq__(self, other: UUID) -> bool:
+//|     def __eq__(self, other: object) -> bool:
 //|         """Two UUID objects are equal if their values match and they are both 128-bit or both 16-bit."""
 //|         ...
 //|

shared-bindings/_bleio/__init__.c

@@ -41,7 +41,8 @@
 #include "shared-bindings/_bleio/Service.h"
 #include "shared-bindings/_bleio/UUID.h"
 
-//| """
+//| """Bluetooth Low Energy (BLE) communication
+//|
 //| The `_bleio` module provides necessary low-level functionality for communicating
 //| using Bluetooth Low Energy (BLE). The '_' prefix indicates this module is meant
 //| for internal use by libraries but not by the end user. Its API may change incompatibly
@@ -50,12 +51,12 @@
 //| `adafruit_ble <https://circuitpython.readthedocs.io/projects/ble/en/latest/>`_
 //| CircuitPython library instead, which builds on `_bleio`, and
 //| provides higher-level convenience functionality, including predefined beacons, clients,
-//| servers.
-//|
-//| .. attribute:: adapter
+//| servers."""
 //|
-//|   BLE Adapter used to manage device discovery and connections.
-//|   This object is the sole instance of `_bleio.Adapter`."""
+
+//| adapter: Adapter
+//| """BLE Adapter used to manage device discovery and connections.
+//| This object is the sole instance of `_bleio.Adapter`."""
 //|
 
 //| class BluetoothError(Exception):