address minor issues: typos, make translate, and sphinx

17 files changed, 286 insertions, 175 deletions

diff --git a/locale/ID.po b/locale/ID.po
index 2451899d9..8597714ef 100644
--- a/locale/ID.po
+++ b/locale/ID.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -546,10 +546,19 @@ msgid "Expected a %q"
 msgstr ""
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 msgid "Expected a Characteristic"
 msgstr ""
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 msgid "Expected a UUID"
 msgstr ""
@@ -572,12 +581,16 @@ msgstr ""
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr "Gagal untuk mendapatkan mutex, status: 0x%08lX"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, fuzzy, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr "Gagal untuk menambahkan karakteristik, status: 0x%08lX"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, fuzzy, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -849,7 +862,7 @@ msgstr "Pin-pin tidak valid"
 msgid "Invalid polarity"
 msgstr ""
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2089,6 +2102,7 @@ msgstr ""
 msgid "math domain error"
 msgstr ""
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2107,11 +2121,6 @@ msgstr ""
 msgid "memory allocation failed, heap is locked"
 msgstr ""
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr "modul tidak ditemukan"
diff --git a/locale/circuitpython.pot b/locale/circuitpython.pot
index c117663a6..ce2370af9 100644
--- a/locale/circuitpython.pot
+++ b/locale/circuitpython.pot
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -535,10 +535,19 @@ msgid "Expected a %q"
 msgstr ""
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 msgid "Expected a Characteristic"
 msgstr ""
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 msgid "Expected a UUID"
 msgstr ""
@@ -561,12 +570,16 @@ msgstr ""
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr ""
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr ""
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -834,7 +847,7 @@ msgstr ""
 msgid "Invalid polarity"
 msgstr ""
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2055,6 +2068,7 @@ msgstr ""
 msgid "math domain error"
 msgstr ""
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2073,11 +2087,6 @@ msgstr ""
 msgid "memory allocation failed, heap is locked"
 msgstr ""
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr ""
diff --git a/locale/de_DE.po b/locale/de_DE.po
index c8f3715a5..25f9a97d0 100644
--- a/locale/de_DE.po
+++ b/locale/de_DE.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2018-07-27 11:55-0700\n"
 "Last-Translator: Pascal Deneaux\n"
 "Language-Team: Sebastian Plamauer, Pascal Deneaux\n"
@@ -539,10 +539,19 @@ msgid "Expected a %q"
 msgstr "Erwartet ein(e) %q"
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 msgid "Expected a Characteristic"
 msgstr "Characteristic wird erwartet"
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 msgid "Expected a UUID"
 msgstr "Eine UUID wird erwartet"
@@ -565,12 +574,16 @@ msgstr ""
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr "Mutex konnte nicht akquiriert werden. Status: 0x%04x"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr "Hinzufügen des Characteristic ist gescheitert. Status: 0x%04x"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -840,7 +853,7 @@ msgstr "Ungültige Pins"
 msgid "Invalid polarity"
 msgstr "Ungültige Polarität"
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2102,6 +2115,7 @@ msgstr "map buffer zu klein"
 msgid "math domain error"
 msgstr ""
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2120,11 +2134,6 @@ msgstr "Speicherzuordnung fehlgeschlagen, Zuweisung von %u Bytes"
 msgid "memory allocation failed, heap is locked"
 msgstr "Speicherzuweisung fehlgeschlagen, der Heap ist gesperrt"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr "Modul nicht gefunden"
diff --git a/locale/en_US.po b/locale/en_US.po
index 086a5065d..47de646bd 100644
--- a/locale/en_US.po
+++ b/locale/en_US.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2018-07-27 11:55-0700\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -535,10 +535,19 @@ msgid "Expected a %q"
 msgstr ""
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 msgid "Expected a Characteristic"
 msgstr ""
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 msgid "Expected a UUID"
 msgstr ""
@@ -561,12 +570,16 @@ msgstr ""
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr ""
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr ""
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -834,7 +847,7 @@ msgstr ""
 msgid "Invalid polarity"
 msgstr ""
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2055,6 +2068,7 @@ msgstr ""
 msgid "math domain error"
 msgstr ""
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2073,11 +2087,6 @@ msgstr ""
 msgid "memory allocation failed, heap is locked"
 msgstr ""
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr ""
diff --git a/locale/en_x_pirate.po b/locale/en_x_pirate.po
index 86cd819ed..6d5a13693 100644
--- a/locale/en_x_pirate.po
+++ b/locale/en_x_pirate.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2018-07-27 11:55-0700\n"
 "Last-Translator: \n"
 "Language-Team: @sommersoft, @MrCertainly\n"
@@ -539,10 +539,19 @@ msgid "Expected a %q"
 msgstr ""
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 msgid "Expected a Characteristic"
 msgstr ""
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 msgid "Expected a UUID"
 msgstr ""
@@ -565,12 +574,16 @@ msgstr ""
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr ""
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr ""
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -838,7 +851,7 @@ msgstr ""
 msgid "Invalid polarity"
 msgstr ""
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2059,6 +2072,7 @@ msgstr ""
 msgid "math domain error"
 msgstr ""
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2077,11 +2091,6 @@ msgstr ""
 msgid "memory allocation failed, heap is locked"
 msgstr ""
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr ""
diff --git a/locale/es.po b/locale/es.po
index 8fb536ea7..9569c478c 100644
--- a/locale/es.po
+++ b/locale/es.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2018-08-24 22:56-0500\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -543,10 +543,19 @@ msgid "Expected a %q"
 msgstr "Se espera un %q"
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 msgid "Expected a Characteristic"
 msgstr "Se esperaba una Característica."
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 msgid "Expected a UUID"
 msgstr "Se esperaba un UUID"
@@ -569,12 +578,16 @@ msgstr "Fallo enviando comando"
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr "No se puede adquirir el mutex, status: 0x%08lX"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, fuzzy, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr "Fallo al añadir caracteristica, err: 0x%08lX"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -845,7 +858,7 @@ msgstr "pines inválidos"
 msgid "Invalid polarity"
 msgstr "Polaridad inválida"
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2112,6 +2125,7 @@ msgstr "map buffer muy pequeño"
 msgid "math domain error"
 msgstr "error de dominio matemático"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2130,11 +2144,6 @@ msgstr "la asignación de memoria falló, asignando %u bytes"
 msgid "memory allocation failed, heap is locked"
 msgstr "la asignación de memoria falló, el heap está bloqueado"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr "módulo no encontrado"
diff --git a/locale/fil.po b/locale/fil.po
index 9b9a58567..3f01e0b6c 100644
--- a/locale/fil.po
+++ b/locale/fil.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2018-12-20 22:15-0800\n"
 "Last-Translator: Timothy <me@timothygarcia.ca>\n"
 "Language-Team: fil\n"
@@ -547,11 +547,20 @@ msgid "Expected a %q"
 msgstr "Umasa ng %q"
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 #, fuzzy
 msgid "Expected a Characteristic"
 msgstr "Hindi mabasa and Characteristic."
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 #, fuzzy
 msgid "Expected a UUID"
@@ -575,12 +584,16 @@ msgstr ""
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr "Nabigo sa pag kuha ng mutex, status: 0x%08lX"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, fuzzy, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr "Nabigo sa paglagay ng characteristic, status: 0x%08lX"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, fuzzy, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -854,7 +867,7 @@ msgstr "Mali ang pins"
 msgid "Invalid polarity"
 msgstr "Mali ang polarity"
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2125,6 +2138,7 @@ msgstr "masyadong maliit ang buffer map"
 msgid "math domain error"
 msgstr "may pagkakamali sa math domain"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2143,11 +2157,6 @@ msgstr "nabigo ang paglalaan ng memorya, paglalaan ng %u bytes"
 msgid "memory allocation failed, heap is locked"
 msgstr "abigo ang paglalaan ng memorya, ang heap ay naka-lock"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr "module hindi nakita"
diff --git a/locale/fr.po b/locale/fr.po
index b6183ca28..5c7d16d43 100644
--- a/locale/fr.po
+++ b/locale/fr.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: 0.1\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2019-04-14 20:05+0100\n"
 "Last-Translator: Pierrick Couturier <arofarn@arofarn.info>\n"
 "Language-Team: fr\n"
@@ -551,11 +551,20 @@ msgid "Expected a %q"
 msgstr "Attendu un %q"
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 #, fuzzy
 msgid "Expected a Characteristic"
 msgstr "Une 'Characteristic' est attendue"
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 #, fuzzy
 msgid "Expected a UUID"
@@ -579,12 +588,16 @@ msgstr ""
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr "Echec de l'obtention de mutex, err 0x%04x"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, fuzzy, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr "Echec de l'ajout de caractéristique, err 0x%04x"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, fuzzy, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -862,7 +875,7 @@ msgstr "Broches invalides"
 msgid "Invalid polarity"
 msgstr "Polarité invalide"
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2157,6 +2170,7 @@ msgstr "tampon trop petit"
 msgid "math domain error"
 msgstr "erreur de domaine math"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2175,11 +2189,6 @@ msgstr "l'allocation de mémoire a échoué en allouant %u octets"
 msgid "memory allocation failed, heap is locked"
 msgstr "l'allocation de mémoire a échoué, le tas est vérrouillé"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr "module introuvable"
diff --git a/locale/it_IT.po b/locale/it_IT.po
index 01729d00b..e7b14ef6b 100644
--- a/locale/it_IT.po
+++ b/locale/it_IT.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2018-10-02 16:27+0200\n"
 "Last-Translator: Enrico Paganin <enrico.paganin@mail.com>\n"
 "Language-Team: \n"
@@ -547,11 +547,20 @@ msgid "Expected a %q"
 msgstr "Atteso un %q"
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 #, fuzzy
 msgid "Expected a Characteristic"
 msgstr "Non è possibile aggiungere Characteristic."
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 #, fuzzy
 msgid "Expected a UUID"
@@ -575,12 +584,16 @@ msgstr ""
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr "Impossibile leggere valore dell'attributo. status: 0x%02x"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, fuzzy, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr "Impossibile fermare advertisement. status: 0x%02x"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, fuzzy, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -855,7 +868,7 @@ msgstr "Pin non validi"
 msgid "Invalid polarity"
 msgstr "Polarità non valida"
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2118,6 +2131,7 @@ msgstr "map buffer troppo piccolo"
 msgid "math domain error"
 msgstr "errore di dominio matematico"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2136,11 +2150,6 @@ msgstr "allocazione di memoria fallita, allocando %u byte"
 msgid "memory allocation failed, heap is locked"
 msgstr "allocazione di memoria fallita, l'heap è bloccato"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr "modulo non trovato"
diff --git a/locale/pl.po b/locale/pl.po
index 33a9f76ae..00170cb3f 100644
--- a/locale/pl.po
+++ b/locale/pl.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2019-03-19 18:37-0700\n"
 "Last-Translator: Radomir Dopieralski <circuitpython@sheep.art.pl>\n"
 "Language-Team: pl\n"
@@ -538,10 +538,19 @@ msgid "Expected a %q"
 msgstr "Oczekiwano %q"
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 msgid "Expected a Characteristic"
 msgstr "Oczekiwano charakterystyki"
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 msgid "Expected a UUID"
 msgstr "Oczekiwano UUID"
@@ -564,12 +573,16 @@ msgstr ""
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr "Nie udało się uzyskać blokady, błąd 0x$04x"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, fuzzy, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr "Nie udało się dodać charakterystyki, błąd 0x$04x"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -839,7 +852,7 @@ msgstr "Złe nóżki"
 msgid "Invalid polarity"
 msgstr "Zła polaryzacja"
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2080,6 +2093,7 @@ msgstr "bufor mapy zbyt mały"
 msgid "math domain error"
 msgstr "błąd domeny"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2098,11 +2112,6 @@ msgstr "alokacja pamięci nie powiodła się, alokowano %u bajtów"
 msgid "memory allocation failed, heap is locked"
 msgstr "alokacja pamięci nie powiodła się, sterta zablokowana"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr "brak modułu"
diff --git a/locale/pt_BR.po b/locale/pt_BR.po
index cc7a6ef3b..bf55570db 100644
--- a/locale/pt_BR.po
+++ b/locale/pt_BR.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2018-10-02 21:14-0000\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -542,11 +542,20 @@ msgid "Expected a %q"
 msgstr "Esperado um"
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 #, fuzzy
 msgid "Expected a Characteristic"
 msgstr "Não é possível adicionar Característica."
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 #, fuzzy
 msgid "Expected a UUID"
@@ -570,12 +579,16 @@ msgstr "Falha ao enviar comando."
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr "Não é possível ler o valor do atributo. status: 0x%02x"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, fuzzy, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr "Não pode parar propaganda. status: 0x%02x"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, fuzzy, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -848,7 +861,7 @@ msgstr "Pinos inválidos"
 msgid "Invalid polarity"
 msgstr ""
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2080,6 +2093,7 @@ msgstr ""
 msgid "math domain error"
 msgstr ""
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2098,11 +2112,6 @@ msgstr ""
 msgid "memory allocation failed, heap is locked"
 msgstr ""
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr ""
diff --git a/locale/zh_Latn_pinyin.po b/locale/zh_Latn_pinyin.po
index f0fbebb99..16f4ecf2c 100644
--- a/locale/zh_Latn_pinyin.po
+++ b/locale/zh_Latn_pinyin.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: circuitpython-cn\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-08-28 16:09-0400\n"
+"POT-Creation-Date: 2019-08-29 14:16-0400\n"
 "PO-Revision-Date: 2019-04-13 10:10-0700\n"
 "Last-Translator: hexthat\n"
 "Language-Team: Chinese Hanyu Pinyin\n"
@@ -539,10 +539,19 @@ msgid "Expected a %q"
 msgstr "Yùqí %q"
 
 #: shared-bindings/bleio/CharacteristicBuffer.c
+#: shared-bindings/bleio/Descriptor.c
 msgid "Expected a Characteristic"
 msgstr "Yùqí de tèdiǎn"
 
-#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Peripheral.c
+#: shared-bindings/bleio/Service.c
+msgid "Expected a Peripheral"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c
+msgid "Expected a Service"
+msgstr ""
+
+#: shared-bindings/bleio/Characteristic.c shared-bindings/bleio/Descriptor.c
 #: shared-bindings/bleio/Service.c
 msgid "Expected a UUID"
 msgstr "Yùqí UUID"
@@ -565,12 +574,16 @@ msgstr "Fāsòng mìnglìng shībài."
 msgid "Failed to acquire mutex, err 0x%04x"
 msgstr "Wúfǎ huòdé mutex, err 0x%04x"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Service.c
 #, c-format
 msgid "Failed to add characteristic, err 0x%04x"
 msgstr "Tiānjiā tèxìng shībài, err 0x%04x"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
+#, c-format
+msgid "Failed to add descriptor, err 0x%04x"
+msgstr ""
+
 #: ports/nrf/common-hal/bleio/Peripheral.c
 #, c-format
 msgid "Failed to add service, err 0x%04x"
@@ -840,7 +853,7 @@ msgstr "Wúxiào de yǐn jiǎo"
 msgid "Invalid polarity"
 msgstr "Wúxiào liǎng jí zhí"
 
-#: shared-bindings/bleio/Service.c
+#: shared-bindings/bleio/Characteristic.c
 msgid "Invalid properties"
 msgstr ""
 
@@ -2092,6 +2105,7 @@ msgstr "dìtú huǎnchōng qū tài xiǎo"
 msgid "math domain error"
 msgstr "shùxué yù cuòwù"
 
+#: ports/nrf/common-hal/bleio/Characteristic.c
 #: ports/nrf/common-hal/bleio/Descriptor.c
 #, c-format
 msgid "max_length must be 0-%d when fixed_length is %s"
@@ -2110,11 +2124,6 @@ msgstr "nèicún fēnpèi shībài, fēnpèi %u zì jié"
 msgid "memory allocation failed, heap is locked"
 msgstr "jìyì tǐ fēnpèi shībài, duī bèi suǒdìng"
 
-#: ports/nrf/common-hal/bleio/Characteristic.c
-#, c-format
-msgid "mnax_length must be 0-%d when fixed_length is %s"
-msgstr ""
-
 #: py/builtinimport.c
 msgid "module not found"
 msgstr "zhǎo bù dào mókuài"
diff --git a/ports/nrf/common-hal/bleio/Characteristic.c b/ports/nrf/common-hal/bleio/Characteristic.c
index 06a312f58..2596f17d8 100644
--- a/ports/nrf/common-hal/bleio/Characteristic.c
+++ b/ports/nrf/common-hal/bleio/Characteristic.c
@@ -135,7 +135,7 @@ void common_hal_bleio_characteristic_construct(bleio_characteristic_obj_t *self,
 
     const mp_int_t max_length_max = fixed_length ? BLE_GATTS_FIX_ATTR_LEN_MAX : BLE_GATTS_VAR_ATTR_LEN_MAX;
     if (max_length < 0 || max_length > max_length_max) {
-        mp_raise_ValueError_varg(translate("mnax_length must be 0-%d when fixed_length is %s"),
+        mp_raise_ValueError_varg(translate("max_length must be 0-%d when fixed_length is %s"),
                                  max_length_max, fixed_length ? "True" : "False");
     }
     self->max_length = max_length;
@@ -249,7 +249,7 @@ void common_hal_bleio_characteristic_add_descriptor(bleio_characteristic_obj_t *
     uint32_t err_code = sd_ble_gatts_descriptor_add(self->handle, &desc_attr, &descriptor->handle);
 
     if (err_code != NRF_SUCCESS) {
-        mp_raise_OSError_msg_varg(translate("Failed to add characteristic, err 0x%04x"), err_code);
+        mp_raise_OSError_msg_varg(translate("Failed to add descriptor, err 0x%04x"), err_code);
     }
 
     mp_obj_list_append(self->descriptor_list, MP_OBJ_FROM_PTR(descriptor));
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);