Move KDoc to be more discoverable

core/src/main/java/android/BluetoothDevice.kt

@@ -9,6 +9,25 @@ import android.content.Context
 import com.juul.able.device.ConnectGattResult
 import com.juul.able.device.CoroutinesDevice
 
+/**
+ * Establishes a connection to the [BluetoothDevice], suspending until connection is successful or
+ * error occurs.
+ *
+ * To cancel an in-flight connection attempt, the Coroutine from which this method was called can be
+ * canceled:
+ *
+ * ```
+ * fun connect(context: Context, device: BluetoothDevice) {
+ *     connectJob = async {
+ *         device.connectGatt(context)
+ *     }
+ * }
+ *
+ * fun cancelConnection() {
+ *     connectJob?.cancel() // cancels the above `connectGatt`
+ * }
+ * ```
+ */
 suspend fun BluetoothDevice.connectGatt(
     context: Context
 ): ConnectGattResult = asCoroutinesDevice().connectGatt(context)

core/src/main/java/device/CoroutinesDevice.kt

@@ -9,7 +9,6 @@ import android.bluetooth.BluetoothGatt.STATE_CONNECTED
 import android.content.Context
 import android.os.RemoteException
 import com.juul.able.Able
-import com.juul.able.android.connectGatt
 import com.juul.able.device.ConnectGattResult.Failure
 import com.juul.able.device.ConnectGattResult.Success
 import com.juul.able.gatt.CoroutinesGatt
@@ -24,25 +23,6 @@ internal class CoroutinesDevice(
     private val device: BluetoothDevice
 ) : Device {
 
-    /**
-     * Establishes a connection to the [BluetoothDevice], suspending until connection is successful
-     * or error occurs.
-     *
-     * To cancel an in-flight connection attempt, the Coroutine from which this method was called
-     * can be canceled:
-     *
-     * ```
-     * fun connect(context: Context, device: BluetoothDevice) {
-     *     connectJob = async {
-     *         device.connectGatt(context)
-     *     }
-     * }
-     *
-     * fun cancelConnection() {
-     *     connectJob?.cancel() // cancels the above `connectGatt`
-     * }
-     * ```
-     */
     override suspend fun connectGatt(context: Context): ConnectGattResult {
         val dispatcher = newSingleThreadContext("$DISPATCHER_NAME@$device")
         val callback = GattCallback(dispatcher)

core/src/main/java/gatt/CoroutinesGatt.kt

@@ -52,32 +52,18 @@ class CoroutinesGatt internal constructor(
         }
     }
 
-    /**
-     * @throws [RemoteException] if underlying [BluetoothGatt.discoverServices] returns `false`.
-     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
-     */
     override suspend fun discoverServices(): GattStatus =
         performBluetoothAction("discoverServices") {
             bluetoothGatt.discoverServices()
         }
 
-    /**
-     * @throws [RemoteException] if underlying [BluetoothGatt.readCharacteristic] returns `false`.
-     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
-     */
     override suspend fun readCharacteristic(
         characteristic: BluetoothGattCharacteristic
     ): OnCharacteristicRead =
         performBluetoothAction("readCharacteristic") {
             bluetoothGatt.readCharacteristic(characteristic)
         }
 
-    /**
-     * @param value applied to [characteristic] when characteristic is written.
-     * @param writeType applied to [characteristic] when characteristic is written.
-     * @throws [RemoteException] if underlying [BluetoothGatt.writeCharacteristic] returns `false`.
-     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
-     */
     override suspend fun writeCharacteristic(
         characteristic: BluetoothGattCharacteristic,
         value: ByteArray,
@@ -89,11 +75,6 @@ class CoroutinesGatt internal constructor(
             bluetoothGatt.writeCharacteristic(characteristic)
         }
 
-    /**
-     * @param value applied to [descriptor] when descriptor is written.
-     * @throws [RemoteException] if underlying [BluetoothGatt.writeDescriptor] returns `false`.
-     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
-     */
     override suspend fun writeDescriptor(
         descriptor: BluetoothGattDescriptor,
         value: ByteArray
@@ -103,10 +84,6 @@ class CoroutinesGatt internal constructor(
             bluetoothGatt.writeDescriptor(descriptor)
         }
 
-    /**
-     * @throws [RemoteException] if underlying [BluetoothGatt.requestMtu] returns `false`.
-     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
-     */
     override suspend fun requestMtu(mtu: Int): OnMtuChanged =
         performBluetoothAction("requestMtu") {
             bluetoothGatt.requestMtu(mtu)

core/src/main/java/gatt/Gatt.kt

@@ -14,8 +14,10 @@ import android.bluetooth.BluetoothGattDescriptor
 import android.bluetooth.BluetoothGattService
 import android.bluetooth.BluetoothProfile
 import android.bluetooth.BluetoothProfile.STATE_DISCONNECTED
+import android.os.RemoteException
 import com.juul.able.Able
 import java.util.UUID
+import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.firstOrNull
 import kotlinx.coroutines.flow.onEach
@@ -80,26 +82,52 @@ class GattStatusFailure(
 
 interface Gatt {
 
+    @FlowPreview
     val onConnectionStateChange: Flow<OnConnectionStateChange>
+
+    @FlowPreview
     val onCharacteristicChanged: Flow<OnCharacteristicChanged>
 
+    /**
+     * @throws [RemoteException] if underlying [BluetoothGatt.discoverServices] returns `false`.
+     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
+     */
     suspend fun discoverServices(): GattStatus
 
     val services: List<BluetoothGattService>
     fun getService(uuid: UUID): BluetoothGattService?
 
+    /**
+     * @throws [RemoteException] if underlying [BluetoothGatt.requestMtu] returns `false`.
+     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
+     */
     suspend fun requestMtu(mtu: Int): OnMtuChanged
 
+    /**
+     * @throws [RemoteException] if underlying [BluetoothGatt.readCharacteristic] returns `false`.
+     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
+     */
     suspend fun readCharacteristic(
         characteristic: BluetoothGattCharacteristic
     ): OnCharacteristicRead
 
+    /**
+     * @param value applied to [characteristic] when characteristic is written.
+     * @param writeType applied to [characteristic] when characteristic is written.
+     * @throws [RemoteException] if underlying [BluetoothGatt.writeCharacteristic] returns `false`.
+     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
+     */
     suspend fun writeCharacteristic(
         characteristic: BluetoothGattCharacteristic,
         value: ByteArray,
         writeType: WriteType
     ): OnCharacteristicWrite
 
+    /**
+     * @param value applied to [descriptor] when descriptor is written.
+     * @throws [RemoteException] if underlying [BluetoothGatt.writeDescriptor] returns `false`.
+     * @throws [ConnectionLost] if [Gatt] disconnects while method is executing.
+     */
     suspend fun writeDescriptor(
         descriptor: BluetoothGattDescriptor,
         value: ByteArray