Documentation Updates

As I've explored the surface area of the Android SDK, I've made a TLC pass on the documentation. This isn't exhaustive, but it includes everything I've looked at.

Note that I've installed within my Android Studio a plugin "Kotlin KDoc Formatter". This has reformatted our KDocs to respect a given width and remove some inconsistent manual formatting. And who has time for that?

There's a few very minor changes beyond just documentation:
- Consistent use of default values
- Normalized the Gradle file
- Changed some method assertions to use `check` rather than `require` as this is semantically more what we're doing - checking state rather than requiring a parameter
- In one instance used `entries` rather than `values` - a suggestion made by Android Studio
- Using an uppercase constant `RIVE_ANDROID`

## To-do
- [x]  Move XML documentation to `attrs.xml`
- [x] Normalize the module `build.gradle`
- [x] Normalize the app `build.gradle`

Diffs=
f3f3c5c4d2 Documentation Updates (#8481)

Co-authored-by: Erik <[email protected]>

.editorconfig

@@ -0,0 +1,2 @@
+[*.kt]
+max_line_length = 100

.gitignore

@@ -30,4 +30,6 @@ build.nexus.sh
 .settings
 .classpath
 kotlin/src/main/jniLibs/*
-kotlin/.cxx
+kotlin/.cxx
+# Notification of missing NDK
+kotlin/src/main/cpp/rive_build_x86.log

.rive_head

@@ -1 +1 @@
-f34822a1249d46f46e6ca60daa6ea3f3045f3981
+f3f3c5c4d20b6caf81400470b7d2908ab61320a0

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020-2021 Rive
+Copyright (c) 2020-2024 Rive
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

app/build.gradle

@@ -1,8 +1,10 @@
-apply plugin: 'com.android.application'
-apply plugin: 'kotlin-android'
+apply plugin: "com.android.application"
+apply plugin: "kotlin-android"
 
 android {
     compileSdk 34
+    namespace "app.rive.runtime.example"
+    ndkVersion "25.1.8937393"
 
     defaultConfig {
         applicationId "app.rive.runtime.example"
@@ -22,18 +24,18 @@ android {
             debuggable true
             minifyEnabled false
             shrinkResources false
-            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro"
         }
         release {
             minifyEnabled true
             shrinkResources true
-            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro"
         }
         preview {
             debuggable true
             minifyEnabled false
             shrinkResources false
-            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro"
             getIsDefault().set(true)
             signingConfig signingConfigs.debug
         }
@@ -47,49 +49,46 @@ android {
         jvmTarget = JavaVersion.VERSION_1_8.toString()
     }
 
-
     buildFeatures {
         viewBinding true
         compose true
     }
-    namespace 'app.rive.runtime.example'
     composeOptions {
-        kotlinCompilerExtensionVersion '1.5.10'
+        kotlinCompilerExtensionVersion "1.5.10"
     }
     packagingOptions {
         resources {
-            excludes += '/META-INF/{AL2.0,LGPL2.1}'
+            excludes += "/META-INF/{AL2.0,LGPL2.1}"
         }
     }
-    ndkVersion '25.1.8937393'
 }
 
 dependencies {
-    implementation fileTree(dir: "libs", include: ["*.jar"])
-    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-    implementation 'androidx.core:core-ktx:1.13.1'
-    implementation 'androidx.appcompat:appcompat:1.7.0'
-    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
-    implementation 'androidx.fragment:fragment-ktx:1.8.3'
-    implementation 'androidx.activity:activity:1.9.2'
-    debugImplementation project(path: ':kotlin')
-    releaseImplementation project(path: ':kotlin')
-    previewImplementation 'app.rive:rive-android:+'
-    implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.8.6'
-    implementation 'com.google.android.material:material:1.12.0'
-    implementation 'androidx.activity:activity-compose:1.9.2'
-    implementation "androidx.compose.ui:ui:$compose_version"
+    implementation "androidx.activity:activity-compose:1.9.2"
+    implementation "androidx.activity:activity:1.9.2"
+    implementation "androidx.appcompat:appcompat:1.7.0"
+    implementation "androidx.compose.material3:material3:1.3.0"
     implementation "androidx.compose.ui:ui-tooling-preview:$compose_version"
-    implementation 'androidx.compose.material3:material3:1.3.0'
-    implementation 'androidx.startup:startup-runtime:1.2.0'
-    implementation 'com.android.volley:volley:1.2.1'
+    implementation "androidx.compose.ui:ui:$compose_version"
+    implementation "androidx.constraintlayout:constraintlayout:2.1.4"
+    implementation "androidx.core:core-ktx:1.13.1"
+    implementation "androidx.fragment:fragment-ktx:1.8.3"
+    implementation "androidx.lifecycle:lifecycle-runtime-ktx:2.8.6"
+    implementation "androidx.startup:startup-runtime:1.2.0"
+    implementation "com.android.volley:volley:1.2.1"
+    implementation "com.google.android.material:material:1.12.0"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    implementation fileTree(dir: "libs", include: ["*.jar"])
+    debugImplementation project(path: ":kotlin")
+    releaseImplementation project(path: ":kotlin")
+    previewImplementation "app.rive:rive-android:+"
 
-    testImplementation 'junit:junit:4.13.2'
-    androidTestImplementation 'androidx.test.ext:junit:1.2.1'
-    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
-    androidTestImplementation 'androidx.compose.ui:ui-test-junit4:1.7.2'
-    androidTestImplementation project(path: ':kotlin')
-    debugImplementation "androidx.compose.ui:ui-tooling:$compose_version"
+    testImplementation "junit:junit:4.13.2"
+    androidTestImplementation "androidx.compose.ui:ui-test-junit4:1.7.2"
+    androidTestImplementation "androidx.test.espresso:espresso-core:3.6.1"
+    androidTestImplementation "androidx.test.ext:junit:1.2.1"
+    androidTestImplementation project(path: ":kotlin")
     debugImplementation "androidx.compose.ui:ui-test-manifest:$compose_version"
-    debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.14'
+    debugImplementation "androidx.compose.ui:ui-tooling:$compose_version"
+    debugImplementation "com.squareup.leakcanary:leakcanary-android:2.14"
 }

app/src/main/java/app/rive/runtime/example/ViewPagerActivity.kt

@@ -17,10 +17,6 @@ import app.rive.runtime.kotlin.controllers.ControllerStateManagement
 class ViewPagerActivity : AppCompatActivity() {
     private lateinit var binding: ViewPagerBinding
 
-    companion object {
-        const val TAG = "ViewPagerActivity"
-    }
-
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
 

build.gradle

@@ -1,20 +1,20 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 apply plugin: "io.github.gradle-nexus.publish-plugin"
-apply plugin: 'com.palantir.git-version'
+apply plugin: "com.palantir.git-version"
 
 def details = versionDetails()
 
 ext {
-    PUBLISH_GROUP_ID = 'app.rive'
+    PUBLISH_GROUP_ID = "app.rive"
     PUBLISH_VERSION = details.lastTag
-    PUBLISH_ARTIFACT_ID = 'rive-android'
+    PUBLISH_ARTIFACT_ID = "rive-android"
 }
 buildscript {
     ext {
-        gradle_version = '8.6.1'
-        kotlin_version = '1.9.22'
+        gradle_version = "8.6.1"
+        kotlin_version = "1.9.22"
         dokkaVersion = "1.4.30"
-        compose_version = '1.6.7'
+        compose_version = "1.6.7"
     }
 
     repositories {
@@ -26,11 +26,11 @@ buildscript {
     }
 
     dependencies {
-        classpath "com.android.tools.build:gradle:$gradle_version"
-        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+        classpath("com.android.tools.build:gradle:$gradle_version")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
         classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokkaVersion}")
         classpath("io.github.gradle-nexus:publish-plugin:1.3.0")
-        classpath "com.palantir.gradle.gitversion:gradle-git-version:3.0.0"
+        classpath("com.palantir.gradle.gitversion:gradle-git-version:3.0.0")
         // NOTE: Do not place your application dependencies here; they belong
         // in the individual module build.gradle files
     }
@@ -44,14 +44,14 @@ allprojects {
     }
 }
 
-tasks.register('cleanDeps', Exec) {
-    workingDir './kotlin/src/main/cpp'
-    commandLine './clean_all.sh'
+tasks.register("cleanDeps", Exec) {
+    workingDir("./kotlin/src/main/cpp")
+    commandLine("./clean_all.sh")
 }
 
-tasks.register('clean', Delete) {
+tasks.register("clean", Delete) {
     dependsOn(cleanDeps)
-    delete rootProject.buildDir
+    delete(rootProject.buildDir)
 }
 
 apply from: "${rootDir}/scripts/publish-root.gradle"

kotlin/build.gradle

@@ -1,11 +1,11 @@
-apply plugin: 'com.android.library'
-apply plugin: 'kotlin-android'
-apply plugin: 'org.jetbrains.dokka'
-
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "org.jetbrains.dokka"
 
 android {
     compileSdk 34
     ndkVersion "25.1.8937393"
+    namespace "app.rive.runtime.kotlin"
 
     defaultConfig {
         minSdkVersion 21
@@ -15,25 +15,28 @@ android {
         consumerProguardFiles "consumer-rules.pro"
         externalNativeBuild {
             cmake {
-                abiFilters 'arm64-v8a', 'armeabi-v7a', 'x86', 'x86_64'
+                abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64"
                 arguments "-DCMAKE_VERBOSE_MAKEFILE=1", "-DANDROID_ALLOW_UNDEFINED_SYMBOLS=ON",
-                        '-DANDROID_CPP_FEATURES=no-exceptions no-rtti', "-DANDROID_STL=c++_shared"
+                        "-DANDROID_CPP_FEATURES=no-exceptions no-rtti", "-DANDROID_STL=c++_shared"
             }
         }
     }
 
     kotlinOptions {
         jvmTarget = JavaVersion.VERSION_1_8.toString()
     }
+
     externalNativeBuild {
         cmake {
-            path file('src/main/cpp/CMakeLists.txt')
-            version '3.22.1'
+            path file("src/main/cpp/CMakeLists.txt")
+            version "3.22.1"
         }
     }
+
     testOptions {
         unitTests.includeAndroidResources = true
     }
+
     dokkaGfm {
         dokkaSourceSets {
             named("main") {
@@ -43,27 +46,26 @@ android {
             }
         }
     }
-    namespace 'app.rive.runtime.kotlin'
 }
+
 configurations.configureEach {
     resolutionStrategy.force "junit:junit:4.13.2"
 }
 
 dependencies {
-    implementation 'com.android.volley:volley:1.2.1'
+    implementation "com.android.volley:volley:1.2.1"
     implementation fileTree(dir: "libs", include: ["*.jar"])
     implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-    implementation 'androidx.core:core-ktx:1.13.1'
-    implementation 'androidx.appcompat:appcompat:1.7.0'
-    implementation 'com.getkeepsafe.relinker:relinker:1.4.5'
-    implementation 'androidx.startup:startup-runtime:1.2.0'
-
-    testImplementation 'junit:junit:4.13.2'
-    testImplementation 'androidx.test:core-ktx:1.6.1'
+    implementation "androidx.core:core-ktx:1.13.1"
+    implementation "androidx.appcompat:appcompat:1.7.0"
+    implementation "com.getkeepsafe.relinker:relinker:1.4.5"
+    implementation "androidx.startup:startup-runtime:1.2.0"
 
+    testImplementation "junit:junit:4.13.2"
+    testImplementation "androidx.test:core-ktx:1.6.1"
 
-    androidTestImplementation 'androidx.test.ext:junit:1.2.1'
-    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
+    androidTestImplementation "androidx.test.ext:junit:1.2.1"
+    androidTestImplementation "androidx.test.espresso:espresso-core:3.6.1"
 }
 
 // Commenting this out, this only really helps when you're doing local dev, but it means our git actions need abd!
@@ -72,8 +74,8 @@ dependencies {
 // }
 
 // task buildJNI(type: Exec) {
-//     workingDir '../cpp'
-//     commandLine './build.rive.for.sh', '-a', getDeviceAbi()
+//     workingDir "../cpp"
+//     commandLine "./build.rive.for.sh", "-a", getDeviceAbi()
 // }
 
 apply from: "${rootProject.projectDir}/scripts/publish-module.gradle"

kotlin/src/androidTest/java/app/rive/runtime/kotlin/fonts/FontHelpersTest.kt

@@ -48,7 +48,7 @@ class FontHelpersTest {
     fun systemFontMatch() {
         val font = FontHelper.getFallbackFont()
         assertNotNull(font)
-        assertEquals(font, Fonts.Font.DEFAULT)
+        assertEquals(Fonts.Font.DEFAULT, font)
 
         val notFound =
             FontHelper.getFallbackFont(
@@ -61,8 +61,8 @@ class FontHelpersTest {
                 Fonts.FontOpts(familyName = "arial", style = "italic")
             )
         assertNotNull(withAlias)
-        assertEquals(withAlias?.name, "Roboto-Italic.ttf")
-        assertEquals(withAlias?.weight, Fonts.Weight.NORMAL)
+        assertEquals("Roboto-Italic.ttf", withAlias?.name)
+        assertEquals(Fonts.Weight.NORMAL, withAlias?.weight)
     }
 
     @Test

kotlin/src/main/cpp/CMakeLists.txt

@@ -84,7 +84,7 @@ file(GLOB SOURCES CONFIGURE_DEPENDS
         src/bindings/*.cpp
         src/helpers/*.cpp
         src/models/*.cpp
-        )
+)
 
 add_library(rive-android SHARED ${SOURCES})
 
@@ -96,14 +96,14 @@ set(static_libs
         rive_skia_renderer
         rive_pls_renderer
         skia
-        )
+)
 
 foreach (X IN LISTS static_libs)
     add_library(${X}-lib STATIC IMPORTED)
     set_target_properties(${X}-lib
             PROPERTIES IMPORTED_LOCATION
             ${CMAKE_CURRENT_SOURCE_DIR}/build/${CONFIG}/${CMAKE_ANDROID_ARCH_ABI}/lib${X}.a
-            )
+    )
 endforeach ()
 
 target_include_directories(rive-android PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
@@ -127,4 +127,4 @@ target_link_libraries(rive-android
         ${egl-lib}
         ${gles-lib}
         jnigraphics
-        )
+)

kotlin/src/main/cpp/build.rive.for.sh

@@ -32,7 +32,7 @@ elif [[ "$OSTYPE" == "darwin"* ]]; then
 fi
 
 if [ -z "$HOST_TAG" ]; then
-    echo "Unkown host tag for OS: $OSTYPE"
+    echo "Unknown host tag for OS: $OSTYPE"
     exit 1
 fi
 

kotlin/src/main/cpp/include/models/dimensions_helper.hpp

@@ -1,5 +1,5 @@
-#ifndef _RIVE_ANDROID_DIMENSIONS_RENDERER_HPP_
-#define _RIVE_ANDROID_DIMENSIONS_RENDERER_HPP_
+#ifndef _RIVE_ANDROID_DIMENSIONS_HELPER_HPP_
+#define _RIVE_ANDROID_DIMENSIONS_HELPER_HPP_
 
 #include "rive/renderer.hpp"
 #include <jni.h>

kotlin/src/main/cpp/src/helpers/general.cpp

@@ -31,7 +31,7 @@ JNIEnv* GetJNIEnv()
     int getEnvStat = g_JVM->GetEnv((void**)&g_env, JNI_VERSION_1_6);
     if (getEnvStat == JNI_EDETACHED)
     {
-        LOGW("JVM::GetEnv - Not Attached.");
+        LOGW("GetJNIEnv - Not Attached.");
         if (g_JVM->AttachCurrentThread((JNIEnv**)&g_env, NULL) != 0)
         {
             LOGE("Failed to attach current thread.");
@@ -43,10 +43,11 @@ JNIEnv* GetJNIEnv()
     }
     else if (getEnvStat == JNI_EVERSION)
     {
-        LOGE("JVM::GetEnv: unsupported version %d", getEnvStat);
+        LOGE("GetJNIEnv: unsupported version %d", getEnvStat);
     }
     return g_env;
 }
+
 void DetachThread()
 {
     if (g_JVM->DetachCurrentThread() != JNI_OK)