From 7ee3db04f3851c15135dbef94c9ce67da4fd1af7 Mon Sep 17 00:00:00 2001 From: dkhawk <107309+dkhawk@users.noreply.github.com> Date: Tue, 21 Oct 2025 16:41:07 -0600 Subject: [PATCH] docs(test): Add Javadoc and KDoc to custom Truth subjects Adds comprehensive documentation to the `LatLngSubject` and `LatLngBoundsSubject` classes for both the Java and Kotlin test sources. This improves their value as a learning resource for developers by explaining their purpose, usage, and the underlying logic for handling geospatial comparisons with tolerance. --- .../mapdemo/truth/LatLngBoundsSubject.java | 22 ++++++++++++++++++- .../example/mapdemo/truth/LatLngSubject.java | 21 +++++++++++++++++- .../kotlindemos/truth/LatLngBoundsSubject.kt | 19 +++++++++++++++- .../kotlindemos/truth/LatLngSubject.kt | 22 +++++++++++++++++-- 4 files changed, 79 insertions(+), 5 deletions(-) diff --git a/ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngBoundsSubject.java b/ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngBoundsSubject.java index f1927a18..ed35c176 100644 --- a/ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngBoundsSubject.java +++ b/ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngBoundsSubject.java @@ -6,6 +6,11 @@ import com.google.common.truth.FailureMetadata; import com.google.common.truth.Subject; import com.google.common.truth.Truth; +/** + * A custom Truth subject for asserting properties of {@link LatLngBounds} objects. + *

+ * To use, static import {@link #assertThat(LatLngBounds)} and call assertions on the subject. + */ public final class LatLngBoundsSubject extends Subject { private final LatLngBounds actual; private static final double TOLERANCE = 1e-5; @@ -15,14 +20,24 @@ public final class LatLngBoundsSubject extends Subject { this.actual = actual; } + /** + * The factory for creating {@link LatLngBoundsSubject} instances. + */ public static Factory latLngBounds() { return LatLngBoundsSubject::new; } + /** + * Creates a {@link LatLngBoundsSubject} for asserting on the given {@link LatLngBounds}. + */ public static LatLngBoundsSubject assertThat(LatLngBounds actual) { return Truth.assertAbout(latLngBounds()).that(actual); } + /** + * Asserts that the given {@link LatLng} is contained within the actual bounds, allowing for + * a small tolerance to account for floating-point inaccuracies. + */ public void containsWithTolerance(LatLng expected) { boolean contains = actual.southwest.latitude - TOLERANCE <= expected.latitude && expected.latitude <= actual.northeast.latitude + TOLERANCE && @@ -32,12 +47,17 @@ public final class LatLngBoundsSubject extends Subject { } } + /** + * Checks if a longitude is within the bounds, correctly handling cases where the bounds + * cross the antimeridian (e.g., from 160 to -160). + */ private boolean isLongitudeWithinBounds(double longitude, LatLngBounds bounds) { if (bounds.southwest.longitude <= bounds.northeast.longitude) { + // Standard case (e.g., from 10 to 20). return longitude >= bounds.southwest.longitude - TOLERANCE && longitude <= bounds.northeast.longitude + TOLERANCE; } else { - // The bounds cross the antimeridian. + // Case where the bounds cross the antimeridian (e.g., from 160 to -160). return longitude >= bounds.southwest.longitude - TOLERANCE || longitude <= bounds.northeast.longitude + TOLERANCE; } diff --git a/ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngSubject.java b/ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngSubject.java index 7103df87..a6e5b997 100644 --- a/ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngSubject.java +++ b/ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngSubject.java @@ -1,11 +1,20 @@ package com.example.mapdemo.truth; import com.google.android.gms.maps.model.LatLng; -import com.google.android.gms.maps.model.LatLngBounds; import com.google.common.truth.FailureMetadata; import com.google.common.truth.Subject; import com.google.common.truth.Truth; +/** + * A custom Truth subject for asserting properties of {@link LatLng} objects. + *

+ * To use, static import {@link #assertThat(LatLng)} and call assertions on the subject. + * 

{@code
+ * LatLng actual = new LatLng(10.0, 20.0);
+ * LatLng expected = new LatLng(10.000001, 20.000001);
+ * assertThat(actual).isNear(expected);
+ * }
+ */ public final class LatLngSubject extends Subject { private final LatLng actual; private static final double TOLERANCE = 1e-6; @@ -15,14 +24,24 @@ public final class LatLngSubject extends Subject { this.actual = actual; } + /** + * The factory for creating {@link LatLngSubject} instances. + */ public static Factory latLngs() { return LatLngSubject::new; } + /** + * Creates a {@link LatLngSubject} for asserting on the given {@link LatLng}. + */ public static LatLngSubject assertThat(LatLng actual) { return Truth.assertAbout(latLngs()).that(actual); } + /** + * Asserts that the actual {@link LatLng} is within a small tolerance of the expected value. + * This is useful for accounting for floating-point inaccuracies. + */ public void isNear(LatLng expected) { if (Math.abs(actual.latitude - expected.latitude) > TOLERANCE || Math.abs(actual.longitude - expected.longitude) > TOLERANCE) { diff --git a/ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngBoundsSubject.kt b/ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngBoundsSubject.kt index 2c044538..167a5f94 100644 --- a/ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngBoundsSubject.kt +++ b/ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngBoundsSubject.kt @@ -6,11 +6,20 @@ import com.google.common.truth.FailureMetadata import com.google.common.truth.Subject import com.google.common.truth.Truth +/** + * A custom Truth subject for asserting properties of [LatLngBounds] objects. + * + * To use, static import [assertThat] and call assertions on the subject. + */ class LatLngBoundsSubject private constructor( failureMetadata: FailureMetadata, 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) { val tolerance = 1e-5 val contains = actual.southwest.latitude - tolerance <= expected.latitude && @@ -21,18 +30,26 @@ class LatLngBoundsSubject private constructor( } } + /** + * Checks if a longitude is within the bounds, correctly handling cases where the bounds + * cross the antimeridian (e.g., from 160 to -160). + */ private fun isLongitudeWithinBounds(longitude: Double, bounds: LatLngBounds, tolerance: Double): Boolean { return if (bounds.southwest.longitude <= bounds.northeast.longitude) { + // Standard case (e.g., from 10 to 20). longitude >= bounds.southwest.longitude - tolerance && longitude <= bounds.northeast.longitude + tolerance } else { - // The bounds cross the antimeridian. + // Case where the bounds cross the antimeridian (e.g., from 160 to -160). longitude >= bounds.southwest.longitude - tolerance || longitude <= bounds.northeast.longitude + tolerance } } companion object { + /** + * Creates a [LatLngBoundsSubject] for asserting on the given [LatLngBounds]. + */ fun assertThat(actual: LatLngBounds): LatLngBoundsSubject { return Truth.assertAbout(::LatLngBoundsSubject).that(actual) } diff --git a/ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngSubject.kt b/ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngSubject.kt index 5ab3feae..efc4f030 100644 --- a/ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngSubject.kt +++ b/ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngSubject.kt @@ -4,22 +4,40 @@ import com.google.android.gms.maps.model.LatLng import com.google.common.truth.FailureMetadata import com.google.common.truth.Subject import com.google.common.truth.Truth +import kotlin.math.abs +/** + * A custom Truth subject for asserting properties of [LatLng] objects. + * + * To use, static import [assertThat] and call assertions on the subject. + * ``` + * val actual = LatLng(10.0, 20.0) + * val expected = LatLng(10.000001, 20.000001) + * assertThat(actual).isNear(expected) + * ``` + */ class LatLngSubject private constructor( failureMetadata: FailureMetadata, 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) { val tolerance = 1e-6 - if (Math.abs(actual.latitude - expected.latitude) > tolerance || - Math.abs(actual.longitude - expected.longitude) > tolerance + if (abs(actual.latitude - expected.latitude) > tolerance || + abs(actual.longitude - expected.longitude) > tolerance ) { failWithActual("expected to be near", expected) } } companion object { + /** + * Creates a [LatLngSubject] for asserting on the given [LatLng]. + */ fun assertThat(actual: LatLng): LatLngSubject { return Truth.assertAbout(::LatLngSubject).that(actual) }