Documentation improvements

Improved documentation for write_gatt_char
Moved hbldh#138 comment for code to docstring and to proper documentation.
Documented the new event loop problem detailed in hbldh#93 and hbldh#125

bleak/backends/bluezdbus/client.py

@@ -389,6 +389,15 @@ async def write_gatt_char(
     ) -> None:
         """Perform a write operation on the specified GATT characteristic.
 
+        NB: the version check below is for the "type" option to the
+        "Characteristic.WriteValue" method that was added to Bluez in 5.50
+        ttps://git.kernel.org/pub/scm/bluetooth/bluez.git/commit?id=fa9473bcc48417d69cc9ef81d41a72b18e34a55a
+        Before that commit, "Characteristic.WriteValue" was only "Write with
+        response". "Characteristic.AcquireWrite" was added in Bluez 5.46
+        https://git.kernel.org/pub/scm/bluetooth/bluez.git/commit/doc/gatt-api.txt?id=f59f3dedb2c79a75e51a3a0d27e2ae06fefc603e
+        which can be used to "Write without response", but for older versions
+        of Bluez, it is not possible to "Write without response".
+
         Args:
             _uuid (str or UUID): The uuid of the characteristics to write to.
             data (bytes or bytearray): The data to send.
@@ -418,14 +427,7 @@ async def write_gatt_char(
                 % str(_uuid)
             )
 
-        # NB: this version check is for the "type" option to the
-        # "Characteristic.WriteValue" method that was added to Bluez in 5.50
-        # https://git.kernel.org/pub/scm/bluetooth/bluez.git/commit?id=fa9473bcc48417d69cc9ef81d41a72b18e34a55a
-        # Before that commit, "Characteristic.WriteValue" was only "Write with
-        # response". "Characteristic.AcquireWrite" was added in Bluez 4.46
-        # https://git.kernel.org/pub/scm/bluetooth/bluez.git/commit/doc/gatt-api.txt?id=f59f3dedb2c79a75e51a3a0d27e2ae06fefc603e
-        # which can be used to "Write without response", but for older versions
-        # of Bluez, it is not possible to "Write without response".
+        # See docstring for details about this handling.
         if not response and self._bluez_version[0] == 5 and self._bluez_version[1] < 46:
             raise BleakError("Write without response requires at least BlueZ 5.46")
         if response or (self._bluez_version[0] == 5 and self._bluez_version[1] > 50):

docs/backends/index.rst

@@ -4,7 +4,7 @@ Bleak backends
 Bleak supports the following operating systems:
 
 * Windows 10, version 16299 (Fall Creators Update) and greater
-* Linux distributions with BlueZ >= 5.43
+* Linux distributions with BlueZ >= 5.43 (See :ref:`linux-backend` for more details)
 * OS X/macOS support via Core Bluetooth API, from at least version 10.11
 
 These pages document platform specific differences from the interface API.

docs/backends/linux.rst

@@ -1,3 +1,5 @@
+.. _linux-backend:
+
 Linux backend
 =============
 
@@ -8,4 +10,26 @@ package. It is written for
 `twisted.internet.asyncioreactor <https://twistedmatrix.com/documents/current/api/twisted.internet.asyncioreactor.html>`_
 one can use it in the `asyncio` way.
 
+.. note::
+
+    You should not create any new event loops when using Bleak with the BlueZ backend, only use the
+    ``asyncio.get_event_loop``. This is due to the way that the
+    `asyncioreactor <https://twistedmatrix.com/documents/current/api/twisted.internet.asyncioreactor.html>`_
+    is used right now.
+
+    If more clients are needed, run these in separate processes right now, until a better recommendation
+    is available.
+
+
+Special handling for ``write_gatt_char``
+----------------------------------------
+
+The ``type`` option to the ``Characteristic.WriteValue``
+method was added to
+`Bluez in 5.50 <https://git.kernel.org/pub/scm/bluetooth/bluez.git/commit?id=fa9473bcc48417d69cc9ef81d41a72b18e34a55a>`_
+Before that commit, ``Characteristic.WriteValue`` was only "Write with response".
+
+``Characteristic.AcquireWrite`` was added in
+`Bluez 5.46 <https://git.kernel.org/pub/scm/bluetooth/bluez.git/commit/doc/gatt-api.txt?id=f59f3dedb2c79a75e51a3a0d27e2ae06fefc603e>`_
+which can be used to "Write without response", but for older versions of Bluez (5.43, 5.44, 5.45), it is not possible to "Write without response".
 

docs/index.rst

@@ -37,7 +37,7 @@ Features
 --------
 
 * Supports Windows 10, version 16299 (Fall Creators Update) or greater
-* Supports Linux distributions with BlueZ >= 5.43
+* Supports Linux distributions with BlueZ >= 5.43 (See :ref:`linux-backend` for more details)
 * OS X/macOS support via Core Bluetooth API, from at least OS X version 10.11
 
 Bleak supports reading, writing and getting notifications from