Merge pull request #126 from NordicPlayground/migration/agp2.6

Migration Nordic Gradle Plugins 2.6.1 and new documentation

Author: philips77

.github/workflows/deploy-to-nexus.yml

@@ -13,8 +13,8 @@ jobs:
           fetch-depth: 0
       - uses: actions/setup-java@v4
         with:
-          distribution: 'corretto'
-          java-version: '17'
+          distribution: 'jetbrains'
+          java-version: '21'
       - shell: bash
         env:
           # The following env variables are used by gradle/publish-module.gradle

README.md

@@ -1,73 +1,25 @@
 # Nordic Common Libraries for Android
-A libraries with Nordic's common code for Android apps.
-
-## Theme
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:theme:<version>'
-```
-
-### Content
-The library contains a few features which are necessary for theming Nordic Semiconductor apps:
-
-* Color palette adopted to the new Material You
-* Typography
-* Nordic theme for dark and light mode
-* Abstract `NordicActivity` class which contain implementations for Nordic's splash screen animation.
-* `WizardStepComponent` for wizard-based app flow.
-* `CircularIcon` an icon with circular shape.
-* Other common views available for different projects.
-
-## Permission
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:permission:<version>'
-```
-
-### Content
-Classes and views related to managing permissions, including Bluetooth and Internet permissions.
 
-## Navigation
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:navigation:<version>'
-```
-
-### Content
-Common navigation components for the app.
-
-## UI Scanner
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:uiscanner:<version>'
-```
+A libraries with Nordic's common code for Android apps.
 
-### Content
-Common Bluetooth LE scanner screen.
+## Documentation
 
-## UI Logger
+The latest documentation can be found [here](https://nordicplayground.github.io/KAndroid-Common-Libraries/html/index.html).
 
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:uilogger:<version>'
-```
+## Usage
 
-### Content
-Common classes related with logging to nRF Logger app.
+To use this library, add the following to your `build.gradle` file:
 
-## Analytics
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:analytics:<version>'
+```gradle
+dependencies {
+    implementation 'no.nordicsemi.android.common:<module>:<version>'
+}
 ```
 
-### Content
-Common views and classes related with gathering analytics data.
-
+## Sample app
 
+Run the sample app to see and test most of the components from the library.
 
+1. Clone the repository.
+2. Open the project in Android Studio.
+3. Run the `app` module on a connected device or emulator.

analytics/Module.md

@@ -0,0 +1,29 @@
+# Module analytics
+
+Set of classes related to Firebase Analytics.
+
+## Configuration
+
+Use of this module requires the following plugins to be applied in the app:
+```kotlin
+if (gradle.startParameter.taskRequests.toString().contains("Release")) {
+    apply("com.google.gms.google-services")
+    apply("com.google.firebase.crashlytics")
+}
+```
+and the _google-services.json_ file to be present in the app module.
+
+Read [Firebase Setup](https://firebase.google.com/docs/android/setup) for more.
+
+> **Note:**
+> 
+> This package requires Hilt, as it's using Dependency Injection to provide the 
+> [NordicAnalytics][no.nordicsemi.android.common.analytics.NordicAnalytics] class.
+
+# Package no.nordicsemi.android.common.analytics
+
+Main API for Nordic analytics. Contains set to methods to log events.
+
+# Package no.nordicsemi.android.common.analytics.view
+
+Set of common views used for enabling analytics in Nordic apps.

analytics/build.gradle.kts

@@ -51,6 +51,12 @@ android {
     namespace = "no.nordicsemi.android.common.analytics"
 }
 
+dokka {
+    dokkaSourceSets.named("main") {
+        includes.from("Module.md")
+    }
+}
+
 dependencies {
     implementation(project(":core"))
     implementation(project(":ui"))

analytics/module-rules.pro

@@ -29,6 +29,8 @@
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+@file:Suppress("unused")
+
 package no.nordicsemi.android.common.analytics
 
 import android.content.Context
@@ -45,14 +47,31 @@ import javax.inject.Singleton
 
 private const val LOG_TAG = "ANALYTICS"
 
+/**
+ * This class is responsible for logging events to Firebase Analytics.
+ *
+ * Use Hilt injection to get an instance of this class.
+ */
 @Singleton
 class NordicAnalytics @Inject internal constructor(
     @ApplicationContext private val context: Context,
     private val repository: AnalyticsPermissionRepository,
 ) {
+    /**
+     * A flow that emits the current Analytics permission data.
+     *
+     * @see AnalyticsPermissionData
+     */
     val permissionData = repository.permissionData
+
     private val firebase by lazy { FirebaseAnalytics.getInstance(context) }
 
+    /**
+     * Logs an event to Firebase Analytics, if the user has granted permission.
+     *
+     * @param name The name of the event. Should be between 1 and 40 characters long.
+     * @param params Optional parameters to be sent with the event.
+     */
     fun logEvent(@Size(min = 1L, max = 40L) name: String, params: Bundle? = null) {
         runBlocking {
             repository.permissionData.firstOrNull()
@@ -64,6 +83,11 @@ class NordicAnalytics @Inject internal constructor(
         }
     }
 
+    /**
+     * Sets whether analytics collection is enabled or disabled.
+     *
+     * @param isEnabled True to enable analytics collection, false to disable it.
+     */
     suspend fun setAnalyticsEnabled(isEnabled: Boolean) {
         if (isEnabled) {
             repository.onPermissionGranted()

analytics/src/main/java/no/nordicsemi/android/common/analytics/NordicAnalytics.kt

@@ -29,6 +29,8 @@
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+@file:Suppress("unused")
+
 package no.nordicsemi.android.common.analytics.view
 
 import androidx.compose.foundation.layout.fillMaxHeight

analytics/src/main/java/no/nordicsemi/android/common/analytics/view/AnalyticsPermissionRequestDialog.kt

@@ -29,6 +29,8 @@
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+@file:Suppress("unused")
+
 package no.nordicsemi.android.common.analytics.view
 
 import androidx.compose.foundation.clickable

analytics/src/main/java/no/nordicsemi/android/common/analytics/view/AnalyticsPermissionSettingsSwitch.kt

@@ -32,7 +32,6 @@ plugins {
     alias(libs.plugins.android.library) apply false
     alias(libs.plugins.hilt) apply false
     alias(libs.plugins.kotlin.parcelize) apply false
-    alias(libs.plugins.kotlin.dokka) apply false
     alias(libs.plugins.compose.compiler) apply false
 
     // Nordic plugins are defined in https://github.com/NordicSemiconductor/Android-Gradle-Plugins
@@ -43,4 +42,18 @@ plugins {
     alias(libs.plugins.nordic.hilt) apply false
     alias(libs.plugins.nordic.nexus.android) apply false
     alias(libs.plugins.nordic.kotlin.android) apply false
+
+    // This plugin is used to generate Dokka documentation.
+    alias(libs.plugins.kotlin.dokka) apply false
+    // This applies Nordic look & feel to generated Dokka documentation.
+    // https://github.com/NordicSemiconductor/Android-Gradle-Plugins/blob/main/plugins/src/main/kotlin/NordicDokkaPlugin.kt
+    alias(libs.plugins.nordic.dokka) apply true
 }
+
+// Configure main Dokka page
+dokka {
+    moduleName.set("Nordic Common Libraries")
+    pluginsConfiguration.html {
+        homepageLink.set("https://github.com/NordicPlayground/Android-Common-Libraries")
+    }
+}

build.gradle.kts

@@ -0,0 +1,7 @@
+# Module core
+
+Common classes and interfaces used by other modules.
+
+# Package no.nordicsemi.android.common.core
+
+Common classes and interfaces used by other modules.

core/Module.md

@@ -55,6 +55,12 @@ android {
     }
 }
 
+dokka {
+    dokkaSourceSets.named("main") {
+        includes.from("Module.md")
+    }
+}
+
 dependencies {
     implementation(libs.androidx.core)
 }

core/build.gradle.kts

@@ -29,7 +29,4 @@
   ~ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
   ~ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   -->
-
-<manifest xmlns:android="http://schemas.android.com/apk/res/android" >
-
-</manifest>
+<manifest/>

core/module-rules.pro

@@ -39,7 +39,16 @@ import android.content.pm.PackageManager
 import android.net.Uri
 import android.os.Build
 
+/**
+ * Base link to the Google Play Store.
+ */
 const val GOOGLE_PLAY_LINK = "https://play.google.com/store/apps/details?id="
+
+/**
+ * AppLauncher is a utility class that can be used to launch an app with a given package name.
+ *
+ * If the activity is not installed, the Google Play Store will be opened.
+ */
 @Suppress("unused")
 object AppLauncher {
     /**

core/src/main/AndroidManifest.xml

@@ -29,10 +29,17 @@
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+@file:Suppress("unused")
+
 package no.nordicsemi.android.common.core
 
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
 
+/**
+ * Application scope for the application.
+ *
+ * Combines [SupervisorJob] with [Dispatchers.Default].
+ */
 val ApplicationScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)

core/src/main/java/no/nordicsemi/android/common/core/AppLauncher.kt

@@ -41,6 +41,14 @@ import androidx.compose.runtime.DisposableEffect
 import androidx.compose.ui.platform.LocalContext
 import androidx.core.content.ContextCompat
 
+/**
+ * Registers a [BroadcastReceiver] that will be automatically unregistered when the composable
+ * is disposed.
+ *
+ * @param intentFilter the [IntentFilter] to register the receiver for.
+ * @param flags additional flags to control the receiver. Default is [ContextCompat.RECEIVER_NOT_EXPORTED].
+ * @param onEvent the callback that will be called when a broadcast is received.
+ */
 @SuppressLint("ComposableNaming")
 @Composable
 fun registerReceiver(

core/src/main/java/no/nordicsemi/android/common/core/ApplicationScope.kt

@@ -37,6 +37,9 @@ import androidx.compose.ui.text.buildAnnotatedString
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.withStyle
 
+/**
+ * Parses the string and makes the text between `<b>` and `</b>` bold using [AnnotatedString].
+ */
 fun String.parseBold(): AnnotatedString {
     val parts = this.split("<b>", "</b>")
     return buildAnnotatedString {

core/src/main/java/no/nordicsemi/android/common/core/BroadcastReceiver+Compose.kt

@@ -34,6 +34,10 @@ package no.nordicsemi.android.common.core
 import kotlinx.coroutines.channels.BufferOverflow
 import kotlinx.coroutines.flow.MutableSharedFlow
 
+/**
+ * Creates a simple [MutableSharedFlow] with a buffer of 1 element and [BufferOverflow.DROP_OLDEST]
+ * strategy.
+ */
 fun <T> simpleSharedFlow() = MutableSharedFlow<T>(
     extraBufferCapacity = 1,
     onBufferOverflow = BufferOverflow.DROP_OLDEST

core/src/main/java/no/nordicsemi/android/common/core/Ext.kt

@@ -33,6 +33,12 @@ package no.nordicsemi.android.common.core
 
 import android.util.SparseArray
 
+/**
+ * Maps the SparseArray to a new SparseArray using the provided modifier.
+ *
+ * @param modifier the modifier to apply to each element.
+ * @return a new SparseArray with the modified elements.
+ */
 fun <T, R> SparseArray<T>.map(
     modifier: (T) -> R,
 ): SparseArray<R> {