Merge remote branch “origin/feature-ors”

Author: Pygmalion69

ors-client/src/main/java/org/nitri/ors/DefaultOrsClient.kt

@@ -25,109 +25,129 @@ import org.nitri.ors.domain.snap.SnapRequest
 import org.nitri.ors.domain.snap.SnapResponse
 import org.nitri.ors.restclient.OpenRouteServiceRestClient
 
+/**
+ * Default implementation of [OrsClient] using the Retrofit based
+ * [OpenRouteServiceRestClient].
+ */
 class DefaultOrsClient(apiKey: String, context: Context) : OrsClient {
     private val api = OpenRouteServiceRestClient.create(apiKey, context)
 
+    /** @inheritDoc */
     override suspend fun getRoute(
         profile: Profile,
         routeRequest: RouteRequest
     ): RouteResponse {
         return api.getRoute(profile.key, routeRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun getRouteGpx(
         profile: Profile,
         routeRequest: RouteRequest
     ): String {
         return api.getRouteGpx(profile.key, routeRequest).body()?.string() ?: ""
     }
 
+    /** @inheritDoc */
     override suspend fun getRouteGeoJson(
         profile: Profile,
         routeRequest: RouteRequest
     ): GeoJsonRouteResponse {
         return api.getRouteGeoJson(profile.key, routeRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun export(
         profile: Profile,
         exportRequest: ExportRequest
     ): ExportResponse {
         return api.export(profile.key, exportRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun exportJson(
         profile: Profile,
         exportRequest: ExportRequest
     ): ExportResponse {
         return api.exportJson(profile.key, exportRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun exportTopoJson(
         profile: Profile,
         exportRequest: ExportRequest
     ): TopoJsonExportResponse {
         return api.exportTopoJson(profile.key, exportRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun getIsochrones(
         profile: Profile,
         isochronesRequest: IsochronesRequest
     ): IsochronesResponse {
         return api.getIsochrones(profile.key, isochronesRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun getMatrix(
         profile: Profile,
         matrixRequest: MatrixRequest
     ): MatrixResponse {
         return api.getMatrix(profile.key, matrixRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun getSnap(
         profile: Profile,
         snapRequest: SnapRequest
     ): SnapResponse {
         return api.getSnap(profile.key, snapRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun getSnapJson(
         profile: Profile,
         snapRequest: SnapRequest
     ): SnapResponse {
         return api.getSnapJson(profile.key, snapRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun getSnapGeoJson(
         profile: Profile,
         snapRequest: SnapRequest
     ): SnapGeoJsonResponse {
         return api.getSnapGeoJson(profile.key, snapRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun getPois(poisRequest: PoisRequest): PoisGeoJsonResponse {
         val raw = api.getPois(poisRequest)
         fun PoisGeoJsonResponse.sanitized(): PoisGeoJsonResponse =
             copy(bbox = bbox?.takeIf { it.size == 4 && it.all(Double::isFinite) })
         return raw.sanitized()
     }
 
+    /** @inheritDoc */
     override suspend fun getOptimization(optimizationRequest: OptimizationRequest): OptimizationResponse {
         return api.getOptimization(optimizationRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun getElevationLine(
         elevationLineRequest: ElevationLineRequest
     ): ElevationLineResponse {
         return api.getElevationLine(elevationLineRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun getElevationPoint(
         elevationPointRequest: ElevationPointRequest
     ): ElevationPointResponse {
         return api.getElevationPoint(elevationPointRequest)
     }
 
+    /** @inheritDoc */
     override suspend fun geocodeSearch(
         text: String,
         apiKey: String,
@@ -166,6 +186,7 @@ class DefaultOrsClient(apiKey: String, context: Context) : OrsClient {
         )
     }
 
+    /** @inheritDoc */
     override suspend fun geocodeAutocomplete(
         apiKey: String,
         text: String,
@@ -202,6 +223,7 @@ class DefaultOrsClient(apiKey: String, context: Context) : OrsClient {
         )
     }
 
+    /** @inheritDoc */
     override suspend fun geocodeStructured(
         apiKey: String,
         address: String?,
@@ -252,6 +274,7 @@ class DefaultOrsClient(apiKey: String, context: Context) : OrsClient {
         )
     }
 
+    /** @inheritDoc */
     override suspend fun geocodeReverse(
         apiKey: String,
         lon: Double,

ors-client/src/main/java/org/nitri/ors/Ors.kt

@@ -2,8 +2,16 @@ package org.nitri.ors
 
 import android.content.Context
 
+/**
+ * Factory for obtaining [OrsClient] instances.
+ */
 object Ors {
-    /** If you already construct the Retrofit API elsewhere, inject it here. */
+    /**
+     * Creates a default [OrsClient] backed by Retrofit.
+     *
+     * @param apiKey API key obtained from openrouteservice.org
+     * @param context Android context used for HTTP client construction
+     */
     @JvmStatic
     fun create(apiKey: String, context: Context): OrsClient = DefaultOrsClient(apiKey, context)
 }

ors-client/src/main/java/org/nitri/ors/OrsClient.kt

@@ -23,6 +23,11 @@ import org.nitri.ors.domain.snap.SnapGeoJsonResponse
 import org.nitri.ors.domain.snap.SnapRequest
 import org.nitri.ors.domain.snap.SnapResponse
 
+/**
+ * Supported routing profiles used across the OpenRouteService endpoints.
+ *
+ * The [key] corresponds to the profile identifier expected by the HTTP API.
+ */
 enum class Profile(val key: String) {
     DRIVING_CAR("driving-car"),
     DRIVING_HGV("driving-hgv"),
@@ -35,44 +40,84 @@ enum class Profile(val key: String) {
     WHEELCHAIR("wheelchair")
 }
 
-@JvmInline value class Lon(val v: Double)
-@JvmInline value class Lat(val v: Double)
+/** Longitude value wrapper used by the DSL builders. */
+@JvmInline
+value class Lon(val v: Double)
+
+/** Latitude value wrapper used by the DSL builders. */
+@JvmInline
+value class Lat(val v: Double)
+
+/** Convenience pair for longitude/latitude coordinates. */
 data class LonLat(val lon: Double, val lat: Double)
 
+/**
+ * Abstraction over the OpenRouteService HTTP API.
+ *
+ * Implementations map these suspending functions to the respective REST
+ * endpoints as documented in the
+ * [OpenRouteService API reference](https://openrouteservice.org/dev/#/api-docs).
+ */
 interface OrsClient {
 
     // Directions
+    /**
+     * Requests a route using the Directions endpoint.
+     * `GET /v2/directions/{profile}`
+     */
     suspend fun getRoute(profile: Profile, routeRequest: RouteRequest): RouteResponse
+
+    /** Retrieves the route as GPX. */
     suspend fun getRouteGpx(profile: Profile, routeRequest: RouteRequest): String
+
+    /** Retrieves the route as GeoJSON feature collection. */
     suspend fun getRouteGeoJson(profile: Profile, routeRequest: RouteRequest): GeoJsonRouteResponse
 
     // Export
+    /** Calls the export endpoint returning plain JSON. */
     suspend fun export(profile: Profile, exportRequest: ExportRequest): ExportResponse
+
+    /** Same as [export] but explicitly requesting JSON output. */
     suspend fun exportJson(profile: Profile, exportRequest: ExportRequest): ExportResponse
+
+    /** Requests TopoJSON output from the export endpoint. */
     suspend fun exportTopoJson(profile: Profile, exportRequest: ExportRequest): TopoJsonExportResponse
 
     // Isochrones
+    /** Accesses the isochrones endpoint. */
     suspend fun getIsochrones(profile: Profile, isochronesRequest: IsochronesRequest): IsochronesResponse
 
     // Matrix
+    /** Calls the matrix endpoint and returns distance/duration matrices. */
     suspend fun getMatrix(profile: Profile, matrixRequest: MatrixRequest): MatrixResponse
 
     // Snapping
+    /** Snaps coordinates to the road network. */
     suspend fun getSnap(profile: Profile, snapRequest: SnapRequest): SnapResponse
+
+    /** Snaps coordinates and returns the JSON variant of the response. */
     suspend fun getSnapJson(profile: Profile, snapRequest: SnapRequest): SnapResponse
+
+    /** Snaps coordinates and returns a GeoJSON response. */
     suspend fun getSnapGeoJson(profile: Profile, snapRequest: SnapRequest): SnapGeoJsonResponse
 
     // POIs
+    /** Queries points of interest and returns a GeoJSON feature collection. */
     suspend fun getPois(poisRequest: PoisRequest): PoisGeoJsonResponse
 
     // Optimization
+    /** Delegates to the VROOM based optimization service. */
     suspend fun getOptimization(optimizationRequest: OptimizationRequest): OptimizationResponse
 
     // Elevation
+    /** Calls the elevation/line endpoint. */
     suspend fun getElevationLine(elevationLineRequest: ElevationLineRequest): ElevationLineResponse
+
+    /** Calls the elevation/point endpoint. */
     suspend fun getElevationPoint(elevationPointRequest: ElevationPointRequest): ElevationPointResponse
 
     // Geocode
+    /** Forward geocoding search endpoint. */
     suspend fun geocodeSearch(
         text: String,
         apiKey: String,
@@ -92,6 +137,7 @@ interface OrsClient {
         size: Int? = 10,
     ): GeocodeSearchResponse
 
+    /** Autocomplete endpoint returning suggestions for a partial query. */
     suspend fun geocodeAutocomplete(
         apiKey: String,
         text: String,
@@ -110,6 +156,7 @@ interface OrsClient {
         size: Int? = null,
     ): GeocodeSearchResponse
 
+    /** Structured forward geocoding using discrete address fields. */
     suspend fun geocodeStructured(
         apiKey: String,
         address: String? = null,
@@ -135,6 +182,7 @@ interface OrsClient {
         size: Int? = null,
     ): GeocodeSearchResponse
 
+    /** Reverse geocoding for a single coordinate. */
     suspend fun geocodeReverse(
         apiKey: String,
         lon: Double,

ors-client/src/main/java/org/nitri/ors/domain/elevation/ElevationDsl.kt

@@ -5,10 +5,11 @@ import kotlinx.serialization.json.JsonElement
 import kotlinx.serialization.json.JsonPrimitive
 import kotlinx.serialization.json.buildJsonArray
 
-// Kotlin DSL for ElevationLineRequest
+/** DSL for building [ElevationLineRequest] instances. */
 inline fun elevationLineRequest(build: ElevationLineRequestBuilder.() -> Unit): ElevationLineRequest =
     ElevationLineRequestBuilder().apply(build).build()
 
+/** Builder used by [elevationLineRequest]. */
 class ElevationLineRequestBuilder {
     var formatIn: String = ElevationFormats.POLYLINE
     var formatOut: String = ElevationFormats.GEOJSON
@@ -40,10 +41,11 @@ class ElevationLineRequestBuilder {
     }
 }
 
-// Kotlin DSL for ElevationPointRequest
+/** DSL for constructing [ElevationPointRequest] objects. */
 inline fun elevationPointRequest(build: ElevationPointRequestBuilder.() -> Unit): ElevationPointRequest =
     ElevationPointRequestBuilder().apply(build).build()
 
+/** Builder used by [elevationPointRequest]. */
 class ElevationPointRequestBuilder {
     var formatIn: String = "point"
     var formatOut: String = "geojson"
@@ -92,4 +94,4 @@ class ElevationPointRequestBuilderJ {
     fun dataset(v: String?) = apply { dsl.dataset = v }
     fun point(lon: Double, lat: Double) = apply { dsl.point(lon, lat) }
     fun build(): ElevationPointRequest = dsl.build()
-}
+}

ors-client/src/main/java/org/nitri/ors/domain/elevation/ElevationPointRequest.kt

@@ -3,15 +3,20 @@ package org.nitri.ors.domain.elevation
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
+/** Request for the `elevation/point` endpoint. */
 @Serializable
 data class ElevationPointRequest(
     @SerialName("format_in")
-    val formatIn: String,                    // Input format, must be provided (e.g., "point")
+    /** Input format, e.g. `point`. */
+    val formatIn: String,
 
     @SerialName("format_out")
-    val formatOut: String = "geojson",       // "geojson" or "point"
+    /** Output format: `geojson` or `point`. */
+    val formatOut: String = "geojson",
 
-    val dataset: String? = null,             // Optional dataset, e.g. "srtm"
+    /** Optional elevation dataset name, e.g. `srtm`. */
+    val dataset: String? = null,
 
-    val geometry: List<Double>               // [lon, lat]
+    /** Coordinate as `[lon, lat]`. */
+    val geometry: List<Double>
 )

ors-client/src/main/java/org/nitri/ors/domain/export/ExportDsl.kt

@@ -1,9 +1,10 @@
 package org.nitri.ors.domain.export
 
-// Kotlin DSL for ExportRequest
+/** DSL for creating [ExportRequest] objects. */
 inline fun exportRequest(build: ExportRequestBuilder.() -> Unit): ExportRequest =
     ExportRequestBuilder().apply(build).build()
 
+/** Builder used by [exportRequest]. */
 class ExportRequestBuilder {
     private var bbox: List<List<Double>>? = null
     private var id: String? = null
@@ -23,7 +24,7 @@ class ExportRequestBuilder {
     }
 }
 
-// Java-friendly builder
+/** Java-friendly builder counterpart. */
 class ExportRequestBuilderJ {
     private var bbox: List<List<Double>>? = null
     private var id: String? = null
@@ -41,4 +42,4 @@ class ExportRequestBuilderJ {
         val i = id ?: "export_request"
         return ExportRequest(bbox = b, id = i, geometry = geometry)
     }
-}
+}

ors-client/src/main/java/org/nitri/ors/domain/export/ExportRequest.kt

@@ -2,9 +2,13 @@ package org.nitri.ors.domain.export
 
 import kotlinx.serialization.Serializable
 
+/** Request payload for the export endpoint. */
 @Serializable
 data class ExportRequest(
-    val bbox: List<List<Double>>, // [minLon, minLat, maxLon, maxLat]
+    /** Bounding box specified as `[[minLon,minLat],[maxLon,maxLat]]`. */
+    val bbox: List<List<Double>>,
+    /** Client-specified identifier. */
     val id: String,
+    /** Whether to include full geometry in the response. */
     val geometry: Boolean? = null
 )