Improve javadoc

composebroadcasts/src/main/java/compose/broadcasts/CBBroadcastReceiver.kt

@@ -28,12 +28,26 @@ import kotlin.coroutines.CoroutineContext
  * A drop-in replacement for Android's [BroadcastReceiver]s that allows users to easily create
  * custom broadcast receivers with the Compose Broadcasts set of APIs.
  *
+ * > **Note**: In case you're creating an instance of this class, it is important to know that
+ * calling `super.onReceive` is important for the library to be able to do its job. Ideally, you
+ * should write all your custom logic inside the composable's `mapToState` lambda and not override
+ * `onReceive` of this class at all.
+ *
  * @param tag The class accepts a unique string value that it uses to identify different instances
  * of [CBBroadcastReceiver]s while trying to fetch its configuration-persisted data. Please make
  * sure to always use a unique `tag` for all your custom CBBroadcastReceiver instances to avoid
  * seeing any unforeseen state/value mismatches.
+ *
+ * @throws IllegalStateException if a pre-existing tag is used. Use [String.isComposeBroadcastsTag]
+ * util extension to check if your tag is already used by the library.
  */
 open class CBBroadcastReceiver(internal val tag: String) : BroadcastReceiver(), CoroutineScope {
+    internal var isLibraryProvidedTag: Boolean = false
+
+    internal constructor(tag: String, isLibraryProvidedTag: Boolean) : this(tag) {
+        this.isLibraryProvidedTag = isLibraryProvidedTag
+    }
+
     override val coroutineContext: CoroutineContext = Dispatchers.Default
 
     override fun onReceive(context: Context?, intent: Intent?) {

composebroadcasts/src/main/java/compose/broadcasts/Composables.kt

@@ -71,6 +71,13 @@ fun <T> rememberBroadcastReceiverAsState(
     receiverExported: Boolean = false,
     mapToState: (Context, Intent) -> T,
 ): State<T> {
+    if (!broadcastReceiver.isLibraryProvidedTag) {
+        check(!broadcastReceiver.tag.isComposeBroadcastsTag) {
+            "The provided `tag` value (${broadcastReceiver.tag}) is already in-use by a " +
+                    "library-provided function. Please choose another unique tag."
+        }
+    }
+
     val context = LocalContext.current
     val coroutineScope = rememberCoroutineScope()
     val currentLifecycleState by rememberCurrentLifecycleState()
@@ -136,7 +143,10 @@ fun rememberIsAirplaneModeOn(): State<Boolean> {
             Settings.Global.AIRPLANE_MODE_ON
         ) != 0,
         intentFilters = listOf(CBIntentFilter(action = CBIntentAction.AirplaneModeChanged)),
-        broadcastReceiver = CBBroadcastReceiver(CBConstants.AIRPLANE_MODE.value),
+        broadcastReceiver = CBBroadcastReceiver(
+            tag = CBConstants.AIRPLANE_MODE.value,
+            isLibraryProvidedTag = true,
+        ),
     ) { receiverContext, _ ->
         Settings.Global.getInt(
             receiverContext.contentResolver,
@@ -155,7 +165,10 @@ fun rememberIsAirplaneModeOn(): State<Boolean> {
 fun rememberBatteryLevel(): State<Int> = rememberBroadcastReceiverAsState(
     initialValue = fetchBatteryLevel(LocalContext.current),
     intentFilters = listOf(CBIntentFilter(action = CBIntentAction.BatteryChanged)),
-    broadcastReceiver = CBBroadcastReceiver(CBConstants.BATTERY_LEVEL.value),
+    broadcastReceiver = CBBroadcastReceiver(
+        tag = CBConstants.BATTERY_LEVEL.value,
+        isLibraryProvidedTag = true,
+    ),
 ) { _, intent ->
     val level: Int = intent.getIntExtra(BatteryManager.EXTRA_LEVEL, -1)
     val scale: Int = intent.getIntExtra(BatteryManager.EXTRA_SCALE, -1)
@@ -179,7 +192,10 @@ private fun fetchBatteryLevel(context: Context): Int {
 fun rememberIsCharging(): State<Boolean> = rememberBroadcastReceiverAsState(
     initialValue = fetchIsCharging(LocalContext.current),
     intentFilters = listOf(CBIntentFilter(CBIntentAction.BatteryChanged)),
-    broadcastReceiver = CBBroadcastReceiver(CBConstants.IS_CHARGING.value),
+    broadcastReceiver = CBBroadcastReceiver(
+        tag = CBConstants.IS_CHARGING.value,
+        isLibraryProvidedTag = true,
+    ),
 ) { _, intent ->
     val status: Int = intent.getIntExtra(BatteryManager.EXTRA_STATUS, -1)
     return@rememberBroadcastReceiverAsState status == BatteryManager.BATTERY_STATUS_CHARGING
@@ -298,7 +314,10 @@ fun rememberPackageInfo(broadcastReceiver: CBBroadcastReceiver): State<CBPackage
 fun rememberCurrentTimeMillis(): State<Long> = rememberBroadcastReceiverAsState(
     initialValue = System.currentTimeMillis(),
     intentFilters = listOf(CBIntentFilter(CBIntentAction.TimeTick)),
-    broadcastReceiver = CBBroadcastReceiver(CBConstants.CURRENT_TIME_MILLIS.value),
+    broadcastReceiver = CBBroadcastReceiver(
+        tag = CBConstants.CURRENT_TIME_MILLIS.value,
+        isLibraryProvidedTag = true,
+    ),
 ) { _, _ -> System.currentTimeMillis() }
 
 /**
@@ -380,7 +399,10 @@ fun rememberIsScreenOn(): State<Boolean> {
             CBIntentFilter(CBIntentAction.ScreenOn),
             CBIntentFilter(CBIntentAction.ScreenOff),
         ),
-        broadcastReceiver = CBBroadcastReceiver(CBConstants.IS_SCREEN_ON.value),
+        broadcastReceiver = CBBroadcastReceiver(
+            tag = CBConstants.IS_SCREEN_ON.value,
+            isLibraryProvidedTag = true,
+        ),
     ) { _, _ -> powerManager.isInteractive }
 }
 
@@ -400,7 +422,10 @@ fun rememberIsHeadsetConnected(): State<Boolean> {
     return rememberBroadcastReceiverAsState(
         initialValue = fetchIsHeadsetConnected(audioManager),
         intentFilters = listOf(CBIntentFilter(CBIntentAction.HeadsetPlug)),
-        broadcastReceiver = CBBroadcastReceiver(CBConstants.HEADSET_INFO.value),
+        broadcastReceiver = CBBroadcastReceiver(
+            tag = CBConstants.HEADSET_INFO.value,
+            isLibraryProvidedTag = true,
+        ),
     ) { _, _ -> fetchIsHeadsetConnected(audioManager) }
 }
 
@@ -449,7 +474,10 @@ fun rememberCurrentInputMethod(): State<CBInputMethodInfo?> {
     return rememberBroadcastReceiverAsState(
         initialValue = fetchCurrentInputMethodInfo(context),
         intentFilters = listOf(CBIntentFilter(CBIntentAction.InputMethodChanged)),
-        broadcastReceiver = CBBroadcastReceiver(CBConstants.INPUT_METHOD.value),
+        broadcastReceiver = CBBroadcastReceiver(
+            tag = CBConstants.INPUT_METHOD.value,
+            isLibraryProvidedTag = true,
+        ),
     ) { _, _ -> fetchCurrentInputMethodInfo(context) }
 }
 

composebroadcasts/src/main/java/compose/broadcasts/Utils.kt

@@ -25,11 +25,12 @@ import androidx.lifecycle.LifecycleEventObserver
 import androidx.lifecycle.compose.LocalLifecycleOwner
 
 /**
- * Convenience extension variable that returns if the given string is an already used tag keyword
- * in the `Compose Broadcasts` library. Make sure to NOT use a string as the `tag` of your custom
- * [CBBroadcastReceiver] class if this value comes out to be `true` for that tag.
+ * Convenience extension variable that returns whether the given string is an already used tag
+ * keyword in the `Compose Broadcasts` library. Make sure to NOT use a string as the `tag` of your
+ * custom [CBBroadcastReceiver] class if this value comes out to be `true` for that tag.
  */
-val String.isLibraryTag: Boolean get() = CBConstants.entries.map { it.value }.contains(this)
+val String.isComposeBroadcastsTag: Boolean
+    get() = CBConstants.entries.map { it.value }.contains(this)
 
 internal const val LOG_TAG = "COMPOSE_BROADCASTS"
 

sample/src/main/java/compose/broadcasts/sample/LocaleReceiver.kt

@@ -21,8 +21,10 @@ import android.util.Log
 import compose.broadcasts.CBBroadcastReceiver
 import java.util.Locale
 
-class LocaleReceiver : CBBroadcastReceiver("current_locale_receiver") {
+class LocaleReceiver : CBBroadcastReceiver(tag = "current_locale_receiver") {
     override fun onReceive(context: Context?, intent: Intent?) {
+        // It is important to call `super.onReceive` for the library to do its job. Ideally, you
+        // should write all your custom logic inside the composable's `mapToState` lambda.
         super.onReceive(context, intent)
         if (intent?.action == Intent.ACTION_LOCALE_CHANGED) {
             Log.d("SAMPLE_APP", "New locale: ${Locale.getDefault().toLanguageTag()}")

sample/src/main/java/compose/broadcasts/sample/PackageInfoReceiver.kt

@@ -17,4 +17,4 @@ package compose.broadcasts.sample
 
 import compose.broadcasts.CBBroadcastReceiver
 
-class PackageInfoReceiver : CBBroadcastReceiver("package_info")
+class PackageInfoReceiver : CBBroadcastReceiver(tag = "package_info")