[gnome-bluetooth/wip/hadess/fixes] lib: Better API docs for _connect_service() API

[Bastien Nocera <hadess src gnome org>]

commit 7f0bf14f92f3b118568e8f1aa08362ccb31951bb
Author: Bastien Nocera <hadess hadess net>
Date:   Tue Aug 9 14:54:25 2022 +0200

    lib: Better API docs for _connect_service() API
    
    Better explain what _connect_service() does, so it's not used for
    devices which can't be "connected" to.

 lib/bluetooth-client.c | 8 ++++++++
 1 file changed, 8 insertions(+)
---
diff --git a/lib/bluetooth-client.c b/lib/bluetooth-client.c
index 7e0adf4b..5dc2522a 100644
--- a/lib/bluetooth-client.c
+++ b/lib/bluetooth-client.c
@@ -1696,6 +1696,14 @@ disconnect_callback (GDBusProxy   *proxy,
  * @callback: (scope async): a #GAsyncReadyCallback to call when the connection is complete
  * @user_data: the data to pass to callback function
  *
+ * This will start the process of connecting to one of the known-connectable
+ * services on the device. This means that it could connect to all the audio
+ * services on a headset, but just to the input service on a keyboard.
+ *
+ * Broadly speaking, this will only have an effect on devices with audio and HID
+ * services, and do nothing if the device doesn't have the "connectable"
+ * property set.
+ *
  * When the connection operation is finished, @callback will be called. You can
  * then call bluetooth_client_connect_service_finish() to get the result of the
  * operation.