NAVAND-777: add docs

Author: dzinad

libnavigation-core/src/main/java/com/mapbox/navigation/core/routerefresh/RouteRefreshController.kt

@@ -2,10 +2,14 @@ package com.mapbox.navigation.core.routerefresh
 
 import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.base.route.NavigationRoute
+import com.mapbox.navigation.core.directions.session.RoutesObserver
 import com.mapbox.navigation.utils.internal.logI
 import kotlinx.coroutines.Job
 
-@OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
+/**
+ * This class lets you manage route refreshes.
+ */
+@ExperimentalPreviewMapboxNavigationAPI
 class RouteRefreshController internal constructor(
     private val routeRefreshParentJob: Job,
     private val plannedRouteRefreshController: PlannedRouteRefreshController,
@@ -15,18 +19,37 @@ class RouteRefreshController internal constructor(
     private val routeRefresherResultProcessor: RouteRefresherResultProcessor,
 ) {
 
+    /**
+     * Register a [RouteRefreshStatesObserver] to be notified of Route refresh state changes.
+     *
+     * @param routeRefreshStatesObserver RouteRefreshStatesObserver
+     */
     fun registerRouteRefreshStateObserver(
         routeRefreshStatesObserver: RouteRefreshStatesObserver
     ) {
         stateHolder.registerRouteRefreshStateObserver(routeRefreshStatesObserver)
     }
 
+    /**
+     * Unregisters a [RouteRefreshStatesObserver].
+     *
+     * @param routeRefreshStatesObserver RouteRefreshStatesObserver
+     */
     fun unregisterRouteRefreshStateObserver(
         routeRefreshStatesObserver: RouteRefreshStatesObserver
     ) {
         stateHolder.unregisterRouteRefreshStateObserver(routeRefreshStatesObserver)
     }
 
+    /**
+     * Immediately refresh current navigation routes.
+     * Listen for refreshed routes using [RoutesObserver].
+     *
+     * The on-demand refresh request is not guaranteed to succeed and call the [RoutesObserver],
+     * [requestImmediateRouteRefresh] invocations cannot be coupled with
+     * [RoutesObserver.onRoutesChanged] callbacks for state management.
+     * You can use [registerRouteRefreshStateObserver] to monitor refresh statuses independently.
+     */
     fun requestImmediateRouteRefresh() {
         val routes = plannedRouteRefreshController.routesToRefresh
         if (routes.isNullOrEmpty()) {

libnavigation-core/src/test/java/com/mapbox/navigation/core/MapboxNavigationBaseTest.kt

@@ -8,6 +8,7 @@ import com.mapbox.android.core.location.LocationEngine
 import com.mapbox.annotation.module.MapboxModuleType
 import com.mapbox.common.MapboxSDKCommon
 import com.mapbox.common.module.provider.MapboxModuleProvider
+import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.base.TimeFormat
 import com.mapbox.navigation.base.formatter.DistanceFormatterOptions
 import com.mapbox.navigation.base.internal.extensions.inferDeviceLocale
@@ -66,7 +67,7 @@ import org.junit.Rule
 import java.io.File
 import java.util.Locale
 
-@OptIn(ExperimentalCoroutinesApi::class)
+@OptIn(ExperimentalCoroutinesApi::class, ExperimentalPreviewMapboxNavigationAPI::class)
 internal open class MapboxNavigationBaseTest {
 
     @get:Rule

libnavigation-core/src/test/java/com/mapbox/navigation/core/routerefresh/RouteRefreshControllerTest.kt

@@ -29,7 +29,7 @@ class RouteRefreshControllerTest {
     private val stateHolder = mockk<RouteRefreshStateHolder>(relaxed = true)
     private val refreshObserversManager = mockk<RefreshObserversManager>(relaxed = true)
     private val resultProcessor = mockk<RouteRefresherResultProcessor>(relaxed = true)
-    private val job = mockk<Job>()
+    private val job = mockk<Job>(relaxed = true)
     private val sut = RouteRefreshController(
         job,
         plannedRouteRefreshController,

libnavigation-core/src/test/java/com/mapbox/navigation/core/routerefresh/RouteRefreshOnDemandIntegrationTest.kt

@@ -1,10 +1,11 @@
 package com.mapbox.navigation.core.routerefresh
 
+import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import org.junit.Assert.assertEquals
 import org.junit.Test
 
-@OptIn(ExperimentalCoroutinesApi::class)
+@OptIn(ExperimentalCoroutinesApi::class, ExperimentalPreviewMapboxNavigationAPI::class)
 internal class RouteRefreshOnDemandIntegrationTest : RouteRefreshIntegrationTest() {
 
     @Test