address minor issues: typos, make translate, and sphinx

4 files changed, 68 insertions, 65 deletions

diff --git a/shared-bindings/bleio/Characteristic.c b/shared-bindings/bleio/Characteristic.c
index 90cd77d17..41d81087c 100644
--- a/shared-bindings/bleio/Characteristic.c
+++ b/shared-bindings/bleio/Characteristic.c
@@ -41,36 +41,37 @@
 //| Stores information about a BLE service characteristic and allows reading
 //| and writing of the characteristic's value.
 //|
-//| There is no regular constructor for a Characteristic. A new local Characteristic can be created
-//| and attached to a Service by calling `Characteristic.add_to_service()`.
-//| Remote Characteristic objects are created by `Central.discover_remote_services()`
-//| or `Peripheral.discover_remote_services()` as part of remote Services.
+//| .. class:: Characteristic
+//|
+//|   There is no regular constructor for a Characteristic. A new local Characteristic can be created
+//|   and attached to a Service by calling `add_to_service()`.
+//|   Remote Characteristic objects are created by `Central.discover_remote_services()`
+//|   or `Peripheral.discover_remote_services()` as part of remote Services.
 //|
 
 //|   .. method:: add_to_service(service, uuid, *, properties=0, read_perm=`Attribute.OPEN`, write_perm=`Attribute.OPEN`, max_length=20, fixed_length=False, initial_value=None)
 //|
-//|   Create a new `Characteristic` object, and add it to this Service.
-//|
-//|   :param bleio.Service service: The service that will provide this characteristic
-//|   :param bleio.UUID uuid: The uuid of the characteristic
-//|   :param int properties: The properties of the characteristic,
-//|      specified as a bitmask of these values bitwise-or'd together:
-//|      `Characteristic.BROADCAST`, `Characteristic.INDICATE`, `Characteristic.NOTIFY`,
-//|      `Characteristic.READ`, `Characteristic.WRITE`, `Characteristic.WRITE_NO_RESPONSE`.
-//|   :param int read_perm: Specifies whether the characteristic can be read by a client, and if so, which
-//|      security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`,
-//|      `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`,
-//|      `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`.
-//|   :param int write_perm: Specifies whether the characteristic can be written by a client, and if so, which
-//|      security mode is required. Values allowed are the same as ``read_perm``.
-//|   :param int max_length: Maximum length in bytes of the characteristic value. The maximum allowed is
+//|     Create a new Characteristic object, and add it to this Service.
+//|
+//|     :param Service service: The service that will provide this characteristic
+//|     :param UUID uuid: The uuid of the characteristic
+//|     :param int properties: The properties of the characteristic,
+//|        specified as a bitmask of these values bitwise-or'd together:
+//|        `BROADCAST`, `INDICATE`, `NOTIFY`, `READ`, `WRITE`, `WRITE_NO_RESPONSE`.
+//|     :param int read_perm: Specifies whether the characteristic can be read by a client, and if so, which
+//|        security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`,
+//|        `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`,
+//|        `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`.
+//|     :param int write_perm: Specifies whether the characteristic can be written by a client, and if so, which
+//|        security mode is required. Values allowed are the same as ``read_perm``.
+//|     :param int max_length: Maximum length in bytes of the characteristic value. The maximum allowed is
 //|      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 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
 //|      filled with zeros.
 //|
-//|   :return: the new `Characteristic`.
+//|     :return: the new Characteristic.
 //|
 STATIC mp_obj_t bleio_characteristic_add_to_service(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     // class is arg[0], which we can ignore.
@@ -150,8 +151,7 @@ STATIC MP_DEFINE_CONST_CLASSMETHOD_OBJ(bleio_characteristic_add_to_service_obj,
 //|
 //|     An int bitmask representing which properties are set, specified as bitwise or'ing of
 //|     of these possible values.
-//|      `~Characteristic.BROADCAST`, `~Characteristic.INDICATE`, `~Characteristic.NOTIFY`,
-//|      `~Characteristic.READ`, `~Characteristic.WRITE`, `~Characteristic.WRITE_NO_RESPONSE`.
+//|     `BROADCAST`, `INDICATE`, `NOTIFY`, `READ`, `WRITE`, `WRITE_NO_RESPONSE`.
 //|
 STATIC mp_obj_t bleio_characteristic_get_properties(mp_obj_t self_in) {
     bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -219,7 +219,7 @@ const mp_obj_property_t bleio_characteristic_value_obj = {
 
 //|   .. attribute:: descriptors
 //|
-//|     A tuple of `bleio.Descriptor` that describe this characteristic. (read-only)
+//|     A tuple of :py:class:`Descriptor` that describe this characteristic. (read-only)
 //|
 STATIC mp_obj_t bleio_characteristic_get_descriptors(mp_obj_t self_in) {
     bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in);
diff --git a/shared-bindings/bleio/Descriptor.c b/shared-bindings/bleio/Descriptor.c
index 39fd21d88..eba2ea1a8 100644
--- a/shared-bindings/bleio/Descriptor.c
+++ b/shared-bindings/bleio/Descriptor.c
@@ -42,31 +42,33 @@
 //| Descriptors are attached to BLE characteristics and provide contextual
 //| information about the characteristic.
 //|
-//| There is no regular constructor for a Descriptor. A new local Descriptor can be created
-//| and attached to a Characteristic by calling `Descriptor.add_to_characteristic()`.
-//| Remote Descriptor objects are created by `Central.discover_remote_services()`
-//| or `Peripheral.discover_remote_services()` as part of remote Characteristics
-//| in the remote Services that are discovered.
-
-//|   .. method:: add_to_characteristic(characteristic, uuid, *, read_perm=`Attribute.OPEN`, write_perm=`Attribute.OPEN`, max_length=20, fixed_length=False, initial_value=b'')
+//| .. class:: Descriptor
+//|
+//|   There is no regular constructor for a Descriptor. A new local Descriptor can be created
+//|   and attached to a Characteristic by calling `add_to_characteristic()`.
+//|   Remote Descriptor objects are created by `Central.discover_remote_services()`
+//|   or `Peripheral.discover_remote_services()` as part of remote Characteristics
+//|   in the remote Services that are discovered.
+//|
+//|   .. classmethod:: add_to_characteristic(characteristic, uuid, *, read_perm=`Attribute.OPEN`, write_perm=`Attribute.OPEN`, max_length=20, fixed_length=False, initial_value=b'')
 //|
-//|   Create a new `Descriptor` object, and add it to this Service.
+//|     Create a new Descriptor object, and add it to this Service.
 //|
-//|   :param bleio.Characteristic characteristic: The characteristic that will hold this descriptor
-//|   :param bleio.UUID uuid: The uuid of the descriptor
-//|   :param int read_perm: Specifies whether the descriptor can be read by a client, and if so, which
-//|      security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`,
-//|      `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`,
-//|      `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`.
-//|   :param int write_perm: Specifies whether the descriptor can be written by a client, and if so, which
-//|      security mode is required. Values allowed are the same as ``read_perm``.
-//|   :param int max_length: Maximum length in bytes of the descriptor value. The maximum allowed is
-//|      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 Characteristic characteristic: The characteristic that will hold this descriptor
+//|     :param UUID uuid: The uuid of the descriptor
+//|     :param int read_perm: Specifies whether the descriptor can be read by a client, and if so, which
+//|        security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`,
+//|        `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`,
+//|        `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`.
+//|     :param int write_perm: Specifies whether the descriptor can be written by a client, and if so, which
+//|        security mode is required. Values allowed are the same as ``read_perm``.
+//|     :param int max_length: Maximum length in bytes of the descriptor value. The maximum allowed is
+//|        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.
 //|
-//|   :return: the new `Descriptor`.
+//|     :return: the new Descriptor.
 //|
 STATIC mp_obj_t bleio_descriptor_add_to_characteristic(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     // class is arg[0], which we can ignore.
diff --git a/shared-bindings/bleio/Peripheral.c b/shared-bindings/bleio/Peripheral.c
index 6ebc406d6..206f1c9a8 100644
--- a/shared-bindings/bleio/Peripheral.c
+++ b/shared-bindings/bleio/Peripheral.c
@@ -61,21 +61,21 @@
 //|
 //| Usage::
 //|
-//|    import bleio
+//|    from bleio import Characteristic, Peripheral, Service
 //|    from adafruit_ble.advertising import ServerAdvertisement
 //|
 //|    # Create a peripheral and start it up.
 //|    peripheral = bleio.Peripheral()
 //|
 //|    # Create a Service and add it to this Peripheral.
-//|    service = peripheral.addService(bleio.UUID(0x180f))
+//|    service = Service.add_to_peripheral(peripheral, bleio.UUID(0x180f))
 //|
 //|    # Create a Characteristic and add it to the Service.
-//|    characteristic = service.addCharacteristic(
+//|    characteristic = Characterist.add_to_service(service,
 //|        bleio.UUID(0x2919), properties=Characteristic.READ | Characteristic.NOTIFY)
 //|
 //|    adv = ServerAdvertisement(peripheral)
-//|    peripheral.start_advertising(adv.advertising_data_bytes, adv.scan_response_bytes)
+//|    peripheral.start_advertising(adv.advertising_data_bytes, scan_response=adv.scan_response_bytes)
 //|
 //|    while not peripheral.connected:
 //|        # Wait for connection.
@@ -132,7 +132,7 @@ const mp_obj_property_t bleio_peripheral_connected_obj = {
 
 //|   .. attribute:: services
 //|
-//|     A `tuple` of `bleio.Service` that are offered by this peripheral. (read-only)
+//|     A tuple of :py:class:`Service` objects offered by this peripheral. (read-only)
 //|
 STATIC mp_obj_t bleio_peripheral_get_services(mp_obj_t self_in) {
     bleio_peripheral_obj_t *self = MP_OBJ_TO_PTR(self_in);
diff --git a/shared-bindings/bleio/Service.c b/shared-bindings/bleio/Service.c
index 134106915..f3bfebb7b 100644
--- a/shared-bindings/bleio/Service.c
+++ b/shared-bindings/bleio/Service.c
@@ -40,24 +40,25 @@
 //|
 //| Stores information about a BLE service and its characteristics.
 //|
-//| There is no regular constructor for a Service. A new local Service can be created
-//| and attached to a Peripheral by calling `Service.add_to_peripheral()`.
-//| Remote Service objects are created by `Central.discover_remote_services()`
-//| or `Peripheral.discover_remote_services()`.
+//| .. class:: Service
+//|
+//|   There is no regular constructor for a Service. A new local Service can be created
+//|   and attached to a Peripheral by calling `add_to_peripheral()`.
+//|   Remote Service objects are created by `Central.discover_remote_services()`
+//|   or `Peripheral.discover_remote_services()`.
 //|
-
 //|   .. classmethod:: add_to_peripheral(peripheral, uuid, *, secondary=False)
 //|
-//|   Create a new `Service` object, identitied by the specified UUID, and add it
-//|   to the given Peripheral.
+//|     Create a new Service object, identitied by the specified UUID, and add it
+//|     to the given Peripheral.
 //|
-//|   To mark the service as secondary, pass `True` as :py:data:`secondary`.
+//|     To mark the service as secondary, pass `True` as :py:data:`secondary`.
 //|
-//|   :param bleio.Peripheral peripheral: The peripheral that will provide this service
-//|   :param bleio.UUID uuid: The uuid of the service
-//|   :param bool secondary: If the service is a secondary one
+//|     :param Peripheral peripheral: The peripheral that will provide this service
+//|     :param UUID uuid: The uuid of the service
+//|     :param bool secondary: If the service is a secondary one
 //
-//|   :return: the new `Service`
+//|     :return: the new Service
 //|
 STATIC mp_obj_t bleio_service_add_to_peripheral(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     // class is arg[0], which we can ignore.
@@ -99,7 +100,7 @@ STATIC MP_DEFINE_CONST_CLASSMETHOD_OBJ(bleio_service_add_to_peripheral_obj, MP_R
 
 //|   .. attribute:: characteristics
 //|
-//|     A tuple of `bleio.Characteristic` that are offered by this service. (read-only)
+//|     A tuple of :py:class:`Characteristic` designating the characteristics that are offered by this service. (read-only)
 //|
 STATIC mp_obj_t bleio_service_get_characteristics(mp_obj_t self_in) {
     bleio_service_obj_t *self = MP_OBJ_TO_PTR(self_in);