refactor(snippets): use version catalog in documentation snippets and update Places SDK

- Update dependencies in snippets (app-compose, app-utils, app-places-ktx)
  to use the Gradle version catalog (libs.*), resolving UseTomlInstead lint
  findings flagged by code scanning.
- Add documentation comments within region tags showing both the recommended
  version catalog configuration (TOML block) and the standalone coordinate
  declaration for non-catalog projects.
- Replace deprecated places-ktx dependency with core Places SDK (libs.places),
  as Kotlin extensions and coroutines are built directly into the Places SDK.
- Add mapsUtils to gradle/libs.versions.toml.
- Add missing androidTest dependencies (ext.junit, espresso.idling.resource)
  to ApiDemos:kotlin-app and update LatLngSubject / LatLngBoundsSubject custom
  Truth subject factories for Kotlin 2.4 / Truth 1.4.5 compatibility.
- Add .kotlin/ compiler directory to .gitignore.

Author: dkhawk

.gitignore

@@ -9,4 +9,5 @@ secrets.properties
 
 # This covers new IDEs, like Antigravity
 .vscode/
-**/bin/
+**/bin/
+.kotlin/

ApiDemos/project/kotlin-app/build.gradle.kts

@@ -93,6 +93,8 @@ dependencies {
 
     // Tests
     testImplementation(libs.junit)
+    androidTestImplementation(libs.ext.junit)
+    androidTestImplementation(libs.espresso.idling.resource)
     androidTestImplementation(libs.junit)
     androidTestImplementation(libs.espresso.core)
     androidTestImplementation(libs.truth)

ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngBoundsSubject.kt

@@ -26,14 +26,18 @@ import com.google.common.truth.Truth
  */
 class LatLngBoundsSubject private constructor(
     failureMetadata: FailureMetadata,
-    private val actual: LatLngBounds
+    private val actual: LatLngBounds?
 ) : Subject(failureMetadata, actual) {
 
     /**
      * Asserts that the given [LatLng] is contained within the actual bounds, allowing for
      * a small tolerance to account for floating-point inaccuracies.
      */
     fun containsWithTolerance(expected: LatLng) {
+        if (actual == null) {
+            failWithActual("expected to contain", expected)
+            return
+        }
         val tolerance = 1e-5
         val contains = actual.southwest.latitude - tolerance <= expected.latitude &&
             expected.latitude <= actual.northeast.latitude + tolerance &&
@@ -60,11 +64,13 @@ class LatLngBoundsSubject private constructor(
     }
 
     companion object {
+        fun latLngBounds(): Factory<LatLngBoundsSubject, LatLngBounds> = Factory(::LatLngBoundsSubject)
+
         /**
          * Creates a [LatLngBoundsSubject] for asserting on the given [LatLngBounds].
          */
-        fun assertThat(actual: LatLngBounds): LatLngBoundsSubject {
-            return Truth.assertAbout(::LatLngBoundsSubject).that(actual)
+        fun assertThat(actual: LatLngBounds?): LatLngBoundsSubject {
+            return Truth.assertAbout(latLngBounds()).that(actual)
         }
     }
 }

ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngSubject.kt

@@ -32,14 +32,18 @@ import kotlin.math.abs
  */
 class LatLngSubject private constructor(
     failureMetadata: FailureMetadata,
-    private val actual: LatLng
+    private val actual: LatLng?
 ) : Subject(failureMetadata, actual) {
 
     /**
      * Asserts that the actual [LatLng] is within a small tolerance of the expected value.
      * This is useful for accounting for floating-point inaccuracies.
      */
     fun isNear(expected: LatLng) {
+        if (actual == null) {
+            failWithActual("expected to be near", expected)
+            return
+        }
         val tolerance = 1e-6
         if (abs(actual.latitude - expected.latitude) > tolerance ||
             abs(actual.longitude - expected.longitude) > tolerance
@@ -63,6 +67,10 @@ class LatLngSubject private constructor(
          * Asserts that the actual [LatLng] is within [tolerance] meters of the [expected] [LatLng].
          */
         fun of(expected: LatLng) {
+            if (actual == null) {
+                failWithActual("expected to be within $tolerance meters of $expected", expected)
+                return
+            }
             val distance = SphericalUtil.computeDistanceBetween(actual, expected)
             if (distance > tolerance) {
                 failWithActual("expected to be within $tolerance meters of $expected [was $distance meters away]", expected)
@@ -71,11 +79,13 @@ class LatLngSubject private constructor(
     }
 
     companion object {
+        fun latLngs(): Factory<LatLngSubject, LatLng> = Factory(::LatLngSubject)
+
         /**
          * Creates a [LatLngSubject] for asserting on the given [LatLng].
          */
-        fun assertThat(actual: LatLng): LatLngSubject {
-            return Truth.assertAbout(::LatLngSubject).that(actual)
+        fun assertThat(actual: LatLng?): LatLngSubject {
+            return Truth.assertAbout(latLngs()).that(actual)
         }
     }
 }

gradle/libs.versions.toml

@@ -38,6 +38,7 @@ materialIconsExtended = "1.7.8"
 # Google Maps & Places
 mapsCompose = "8.4.0"
 mapsKtx = "6.3.0"
+mapsUtils = "5.1.1"
 places = "5.3.0"
 playServicesMaps = "20.0.0"
 secretsGradlePlugin = "2.0.1"
@@ -102,6 +103,7 @@ ui-tooling-preview = { module = "androidx.compose.ui:ui-tooling-preview", versio
 # Maps & Places
 maps-compose = { module = "com.google.maps.android:maps-compose", version.ref = "mapsCompose" }
 maps-ktx = { group = "com.google.maps.android", name = "maps-ktx", version.ref = "mapsKtx" }
+maps-utils = { module = "com.google.maps.android:android-maps-utils", version.ref = "mapsUtils" }
 maps-utils-ktx = { group = "com.google.maps.android", name = "maps-utils-ktx", version.ref = "mapsKtx" }
 places = { group = "com.google.android.libraries.places", name = "places", version.ref = "places" }
 play-services-maps = { group = "com.google.android.gms", name = "play-services-maps", version.ref = "playServicesMaps" }

snippets/app-compose/build.gradle.kts

@@ -85,8 +85,21 @@ dependencies {
     implementation(libs.lifecycle.runtime.ktx)
     // [END_EXCLUDE]
 
+    // Modern Android projects use version catalogs to manage dependencies. To include the Maps Compose library,
+    // first add the following to your gradle/libs.versions.toml file:
+    //
+    // [versions]
+    // mapsCompose = "8.4.0"
+    //
+    // [libraries]
+    // maps-compose = { module = "com.google.maps.android:maps-compose", version.ref = "mapsCompose" }
+    //
     // Android Maps Compose composables for the Maps SDK for Android
-    implementation("com.google.maps.android:maps-compose:8.4.0")
+    implementation(libs.maps.compose)
+
+    // If your project does not use a version catalog, you can use the following dependency instead:
+    //
+    //    implementation("com.google.maps.android:maps-compose:8.4.0")
 }
 // [END maps_android_compose_dependency]
 

snippets/app-places-ktx/build.gradle.kts

@@ -80,8 +80,21 @@ dependencies {
     androidTestImplementation(libs.espresso.core)
     // [END_EXCLUDE]
 
-    // KTX for the Places SDK for Android library
-    implementation("com.google.maps.android:places-ktx:5.0.0")
+    // Modern Android projects use version catalogs to manage dependencies. To include the Places SDK for Android,
+    // first add the following to your gradle/libs.versions.toml file:
+    //
+    // [versions]
+    // places = "5.3.0"
+    //
+    // [libraries]
+    // places = { group = "com.google.android.libraries.places", name = "places", version.ref = "places" }
+    //
+    // Places SDK for Android (Kotlin extensions and coroutines are built directly into the Places SDK)
+    implementation(libs.places)
+
+    // If your project does not use a version catalog, you can use the following dependency instead:
+    //
+    //    implementation("com.google.android.libraries.places:places:5.3.0")
 }
 // [END places_android_ktx_install_snippet]
 

snippets/app-utils/build.gradle.kts

@@ -79,10 +79,23 @@ dependencies {
     androidTestImplementation(libs.espresso.core)
     // [END_EXCLUDE]
 
+    // Modern Android projects use version catalogs to manage dependencies. To include the Maps Utility library,
+    // first add the following to your gradle/libs.versions.toml file:
+    //
+    // [versions]
+    // mapsUtils = "5.1.1"
+    //
+    // [libraries]
+    // maps-utils = { module = "com.google.maps.android:android-maps-utils", version.ref = "mapsUtils" }
+    //
     // Utility Library for Maps SDK for Android
     // You do not need to add a separate dependency for the Maps SDK for Android
     // since this library builds in the compatible version of the Maps SDK.
-    implementation("com.google.maps.android:android-maps-utils:5.1.1")
+    implementation(libs.maps.utils)
+
+    // If your project does not use a version catalog, you can use the following dependency instead:
+    //
+    //    implementation("com.google.maps.android:android-maps-utils:5.1.1")
 }
 // [END maps_android_utils_install_snippet]