Rename experimental API annotation (#1114)

twyatt · web-flow · commit 99075405138a · 2026-07-08T23:27:51.000Z
diff --git a/kable-core/api/android/kable-core.api b/kable-core/api/android/kable-core.api
@@ -126,6 +126,9 @@ public abstract interface class com/juul/kable/DiscoveredService : com/juul/kabl
 public abstract interface annotation class com/juul/kable/ExperimentalApi : java/lang/annotation/Annotation {
 }
 
+public abstract interface annotation class com/juul/kable/ExperimentalKableApi : java/lang/annotation/Annotation {
+}
+
 public abstract class com/juul/kable/Filter {
 }
 
diff --git a/kable-core/api/jvm/kable-core.api b/kable-core/api/jvm/kable-core.api
@@ -85,6 +85,9 @@ public abstract interface class com/juul/kable/DiscoveredService : com/juul/kabl
 public abstract interface annotation class com/juul/kable/ExperimentalApi : java/lang/annotation/Annotation {
 }
 
+public abstract interface annotation class com/juul/kable/ExperimentalKableApi : java/lang/annotation/Annotation {
+}
+
 public abstract class com/juul/kable/Filter {
 }
 
diff --git a/kable-core/build.gradle.kts b/kable-core/build.gradle.kts
@@ -57,7 +57,7 @@ kotlin {
     sourceSets {
         all {
             languageSettings {
-                optIn("com.juul.kable.ExperimentalApi")
+                optIn("com.juul.kable.ExperimentalKableApi")
                 optIn("com.juul.kable.KableInternalApi")
                 optIn("kotlin.concurrent.atomics.ExperimentalAtomicApi")
                 optIn("kotlin.js.ExperimentalWasmJsInterop")
diff --git a/kable-core/src/androidMain/kotlin/BluetoothDeviceAndroidPeripheral.kt b/kable-core/src/androidMain/kotlin/BluetoothDeviceAndroidPeripheral.kt
@@ -100,7 +100,7 @@ internal class BluetoothDeviceAndroidPeripheral(
 
     override val address: String = requireNonZeroAddress(bluetoothDevice.address)
 
-    @ExperimentalApi
+    @ExperimentalKableApi
     override val name: String?
         get() = bluetoothDevice.name
 
@@ -171,7 +171,7 @@ internal class BluetoothDeviceAndroidPeripheral(
     override suspend fun maximumWriteValueLengthForType(writeType: WriteType): Int =
         (mtu.value ?: DEFAULT_ATT_MTU) - ATT_MTU_HEADER_SIZE
 
-    @ExperimentalApi // Experimental until Web Bluetooth advertisements APIs are stable.
+    @ExperimentalKableApi // Experimental until Web Bluetooth advertisements APIs are stable.
     override suspend fun rssi(): Int =
         connectionOrThrow().execute<OnReadRemoteRssi> {
             readRemoteRssiOrThrow()
diff --git a/kable-core/src/androidMain/kotlin/Peripheral.kt b/kable-core/src/androidMain/kotlin/Peripheral.kt
@@ -11,7 +11,7 @@ public actual fun Peripheral(
     return Peripheral(advertisement.bluetoothDevice, builderAction)
 }
 
-@ExperimentalApi // Experimental while evaluating if this API introduces any footguns.
+@ExperimentalKableApi // Experimental while evaluating if this API introduces any footguns.
 public fun Peripheral(
     scanResult: ScanResult,
     builderAction: PeripheralBuilderAction,
diff --git a/kable-core/src/appleMain/kotlin/CBPeripheralCoreBluetoothPeripheral.kt b/kable-core/src/appleMain/kotlin/CBPeripheralCoreBluetoothPeripheral.kt
@@ -113,7 +113,7 @@ internal class CBPeripheralCoreBluetoothPeripheral(
         connection.value
             ?: throw NotConnectedException("Connection not established, current state: ${state.value}")
 
-    @ExperimentalApi
+    @ExperimentalKableApi
     override val name: String?
         get() = cbPeripheral.name
 
@@ -176,7 +176,7 @@ internal class CBPeripheralCoreBluetoothPeripheral(
         return cbPeripheral.maximumWriteValueLengthForType(type).toInt()
     }
 
-    @ExperimentalApi // Experimental until Web Bluetooth advertisements APIs are stable.
+    @ExperimentalKableApi // Experimental until Web Bluetooth advertisements APIs are stable.
     @Throws(CancellationException::class, IOException::class)
     override suspend fun rssi(): Int = connectionOrThrow().execute<DidReadRssi> {
         cbPeripheral.readRSSI()
diff --git a/kable-core/src/commonMain/kotlin/Bluetooth.kt b/kable-core/src/commonMain/kotlin/Bluetooth.kt
@@ -73,7 +73,7 @@ public object Bluetooth {
      *
      * This function is idempotent.
      */
-    @ExperimentalApi // Due to the inability to query Bluetooth support w/o showing a dialog on Apple, this function may be removed.
+    @ExperimentalKableApi // Due to the inability to query Bluetooth support w/o showing a dialog on Apple, this function may be removed.
     public suspend fun isSupported(): Boolean = isBluetoothSupported()
 }
 
diff --git a/kable-core/src/commonMain/kotlin/ExperimentalApi.kt b/kable-core/src/commonMain/kotlin/ExperimentalApi.kt
diff --git a/kable-core/src/commonMain/kotlin/ExperimentalKableApi.kt b/kable-core/src/commonMain/kotlin/ExperimentalKableApi.kt
@@ -0,0 +1,44 @@
+package com.juul.kable
+
+import kotlin.RequiresOptIn.Level.ERROR
+import kotlin.annotation.AnnotationRetention.BINARY
+import kotlin.annotation.AnnotationTarget.ANNOTATION_CLASS
+import kotlin.annotation.AnnotationTarget.CLASS
+import kotlin.annotation.AnnotationTarget.CONSTRUCTOR
+import kotlin.annotation.AnnotationTarget.FIELD
+import kotlin.annotation.AnnotationTarget.FUNCTION
+import kotlin.annotation.AnnotationTarget.LOCAL_VARIABLE
+import kotlin.annotation.AnnotationTarget.PROPERTY
+import kotlin.annotation.AnnotationTarget.PROPERTY_GETTER
+import kotlin.annotation.AnnotationTarget.PROPERTY_SETTER
+import kotlin.annotation.AnnotationTarget.TYPEALIAS
+import kotlin.annotation.AnnotationTarget.VALUE_PARAMETER
+
+@Deprecated(
+    message = "Renamed to ExperimentalKableApi",
+    replaceWith = ReplaceWith("ExperimentalKableApi"),
+    level = DeprecationLevel.ERROR,
+)
+@Target(TYPEALIAS, FUNCTION, PROPERTY, CLASS)
+@Retention(BINARY)
+@RequiresOptIn(level = ERROR)
+public annotation class ExperimentalApi
+
+/** Marks API that is experimental and/or likely to change. */
+@RequiresOptIn(level = ERROR)
+@Retention(BINARY)
+@Target(
+    CLASS,
+    ANNOTATION_CLASS,
+    PROPERTY,
+    FIELD,
+    LOCAL_VARIABLE,
+    VALUE_PARAMETER,
+    CONSTRUCTOR,
+    FUNCTION,
+    PROPERTY_GETTER,
+    PROPERTY_SETTER,
+    TYPEALIAS,
+)
+@MustBeDocumented
+public annotation class ExperimentalKableApi
diff --git a/kable-core/src/commonMain/kotlin/Peripheral.kt b/kable-core/src/commonMain/kotlin/Peripheral.kt
@@ -115,7 +115,7 @@ public interface Peripheral : AutoCloseable {
      * This API is experimental as it may be changed to a [StateFlow] in the future (to notify of
      * name changes on Apple platform).
      */
-    @ExperimentalApi
+    @ExperimentalKableApi
     public val name: String?
 
     /**
@@ -185,7 +185,7 @@ public interface Peripheral : AutoCloseable {
      * @throws NotConnectedException if invoked without an established [connection][connect].
      * @throws UnsupportedOperationException on JavaScript.
      */
-    @ExperimentalApi
+    @ExperimentalKableApi
     @Throws(CancellationException::class, IOException::class)
     public suspend fun rssi(): Int
 
diff --git a/kable-core/src/commonMain/kotlin/Profile.kt b/kable-core/src/commonMain/kotlin/Profile.kt
@@ -57,7 +57,7 @@ public interface Characteristic {
 
     @JvmInline
     @Suppress("ktlint:standard:annotation")
-    public value class Properties @ExperimentalApi constructor(public val value: Int) {
+    public value class Properties @ExperimentalKableApi constructor(public val value: Int) {
         internal infix fun or(other: Properties): Properties = Properties(value or other.value)
         internal infix fun and(other: Properties): Properties = Properties(value and other.value)
         override fun toString(): String = buildList {
diff --git a/kable-core/src/commonMain/kotlin/Uuid.kt b/kable-core/src/commonMain/kotlin/Uuid.kt
@@ -296,21 +296,21 @@ private val BluetoothDescriptors by lazy {
 }
 
 /** Gets a service [Uuid] from a known service [name]. */
-@ExperimentalApi
+@ExperimentalKableApi
 public fun Uuid.Companion.service(name: String): Uuid =
     BluetoothServices[name]
         ?.let { Bluetooth.BaseUuid + it }
         ?: throw NoSuchElementException("Unknown Bluetooth service name: $name")
 
 /** Gets a characteristic [Uuid] from a known characteristic [name]. */
-@ExperimentalApi
+@ExperimentalKableApi
 public fun Uuid.Companion.characteristic(name: String): Uuid =
     BluetoothCharacteristics[name]
         ?.let { Bluetooth.BaseUuid + it }
         ?: throw NoSuchElementException("Unknown Bluetooth characteristic name: $name")
 
 /** Gets a descriptor [Uuid] from a known descriptor [name]. */
-@ExperimentalApi
+@ExperimentalKableApi
 public fun Uuid.Companion.descriptor(name: String): Uuid =
     BluetoothDescriptors[name]
         ?.let { Bluetooth.BaseUuid + it }
diff --git a/kable-core/src/jvmMain/kotlin/com/juul/kable/btleplug/BtleplugPeripheral.kt b/kable-core/src/jvmMain/kotlin/com/juul/kable/btleplug/BtleplugPeripheral.kt
@@ -4,7 +4,7 @@ import com.juul.kable.BasePeripheral
 import com.juul.kable.Characteristic
 import com.juul.kable.Descriptor
 import com.juul.kable.DiscoveredService
-import com.juul.kable.ExperimentalApi
+import com.juul.kable.ExperimentalKableApi
 import com.juul.kable.Identifier
 import com.juul.kable.NotConnectedException
 import com.juul.kable.ObservationEvent.CharacteristicChange
@@ -24,12 +24,9 @@ import com.juul.kable.btleplug.ffi.isAdapterOn
 import com.juul.kable.coroutines.childSupervisor
 import com.juul.kable.logs.Logger
 import com.juul.kable.logs.Logging
-import com.juul.kable.properties
 import com.juul.kable.sharedRepeatableAction
 import com.juul.kable.suspendUntil
 import com.juul.kable.unwrapCancellationException
-import jdk.internal.joptsimple.internal.Messages.message
-import jdk.internal.org.objectweb.asm.Type.getDescriptor
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.CoroutineStart
 import kotlinx.coroutines.Dispatchers
@@ -187,7 +184,7 @@ internal class BtleplugPeripheral(
     override suspend fun maximumWriteValueLengthForType(writeType: WriteType): Int =
         DEFAULT_ATT_MTU - ATT_MTU_HEADER_SIZE
 
-    @ExperimentalApi
+    @ExperimentalKableApi
     override suspend fun rssi(): Int = withContext(Dispatchers.IO) {
         ffi.properties().rssi?.toInt() ?: Int.MIN_VALUE
     }
diff --git a/kable-core/src/webMain/kotlin/BluetoothDeviceWebBluetoothPeripheral.kt b/kable-core/src/webMain/kotlin/BluetoothDeviceWebBluetoothPeripheral.kt
@@ -64,7 +64,7 @@ internal class BluetoothDeviceWebBluetoothPeripheral(
     override val services = _services.asStateFlow()
     private fun servicesOrThrow() = services.value ?: error("Services have not been discovered")
 
-    @ExperimentalApi
+    @ExperimentalKableApi
     override val name: String? get() = bluetoothDevice.name
 
     private val observers = Observers<DataView>(this, logging, false, observationExceptionHandler)
@@ -137,7 +137,7 @@ internal class BluetoothDeviceWebBluetoothPeripheral(
      *
      * @throws UnsupportedOperationException If feature is not enabled and/or supported.
      */
-    @ExperimentalApi
+    @ExperimentalKableApi
     override suspend fun rssi(): Int {
         if (!isWatchingAdvertisementsSupported) {
             throw UnsupportedOperationException("RSSI not supported")
diff --git a/samples/sensortag/shared/build.gradle.kts b/samples/sensortag/shared/build.gradle.kts
@@ -54,7 +54,7 @@ kotlin {
 
     sourceSets {
         all {
-            languageSettings.optIn("com.juul.kable.ExperimentalApi")
+            languageSettings.optIn("com.juul.kable.ExperimentalKableApi")
             languageSettings.optIn("kotlin.uuid.ExperimentalUuidApi")
         }
 
diff --git a/samples/sensortag/shared/src/commonMain/kotlin/features/scan/ScanScreenModel.kt b/samples/sensortag/shared/src/commonMain/kotlin/features/scan/ScanScreenModel.kt
@@ -4,7 +4,7 @@ import cafe.adriel.voyager.core.model.ScreenModel
 import cafe.adriel.voyager.core.model.screenModelScope
 import cafe.adriel.voyager.core.screen.Screen
 import com.juul.kable.Bluetooth
-import com.juul.kable.ExperimentalApi
+import com.juul.kable.ExperimentalKableApi
 import com.juul.kable.Peripheral
 import com.juul.kable.PlatformAdvertisement
 import com.juul.kable.logs.Logging.Level.Data
@@ -95,7 +95,7 @@ class ScanScreenModel(
 
     init {
         screenModelScope.launch {
-            @OptIn(ExperimentalApi::class)
+            @OptIn(ExperimentalKableApi::class)
             isBluetoothSupported.value = Bluetooth.isSupported()
         }
     }

Original file line number	Diff line number	Diff line change
`@@ -126,6 +126,9 @@ public abstract interface class com/juul/kable/DiscoveredService : com/juul/kabl`
`126`	`126`	`public abstract interface annotation class com/juul/kable/ExperimentalApi : java/lang/annotation/Annotation {`
`127`	`127`	`}`
`128`	`128`
	`129`	`+public abstract interface annotation class com/juul/kable/ExperimentalKableApi : java/lang/annotation/Annotation {`
	`130`	`+}`
	`131`	`+`
`129`	`132`	`public abstract class com/juul/kable/Filter {`
`130`	`133`	`}`
`131`	`134`
Original file line number	Diff line number	Diff line change
`@@ -85,6 +85,9 @@ public abstract interface class com/juul/kable/DiscoveredService : com/juul/kabl`
`85`	`85`	`public abstract interface annotation class com/juul/kable/ExperimentalApi : java/lang/annotation/Annotation {`
`86`	`86`	`}`
`87`	`87`
	`88`	`+public abstract interface annotation class com/juul/kable/ExperimentalKableApi : java/lang/annotation/Annotation {`
	`89`	`+}`
	`90`	`+`
`88`	`91`	`public abstract class com/juul/kable/Filter {`
`89`	`92`	`}`
`90`	`93`
Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@ public actual fun Peripheral(`
`11`	`11`	`return Peripheral(advertisement.bluetoothDevice, builderAction)`
`12`	`12`	`}`
`13`	`13`
`14`		`-@ExperimentalApi // Experimental while evaluating if this API introduces any footguns.`
	`14`	`+@ExperimentalKableApi // Experimental while evaluating if this API introduces any footguns.`
`15`	`15`	`public fun Peripheral(`
`16`	`16`	`scanResult: ScanResult,`
`17`	`17`	`builderAction: PeripheralBuilderAction,`
Original file line number	Diff line number	Diff line change
`@@ -73,7 +73,7 @@ public object Bluetooth {`
`73`	`73`	`*`
`74`	`74`	`* This function is idempotent.`
`75`	`75`	`*/`
`76`		`- @ExperimentalApi // Due to the inability to query Bluetooth support w/o showing a dialog on Apple, this function may be removed.`
	`76`	`+ @ExperimentalKableApi // Due to the inability to query Bluetooth support w/o showing a dialog on Apple, this function may be removed.`
`77`	`77`	`public suspend fun isSupported(): Boolean = isBluetoothSupported()`
`78`	`78`	`}`
`79`	`79`