From 0630b68647efef21037f4e9678f7f15e83e88a4e Mon Sep 17 00:00:00 2001
From: Jay Ohms <jay.ohms@gmail.com>
Date: Sun, 25 Feb 2024 13:14:33 -0500
Subject: [PATCH] Add missing TurboSessionNavHostFragment API documentation

---
 .../demo/main/MainSessionNavHostFragment.kt   |  3 --
 .../session/TurboSessionNavHostFragment.kt    | 46 ++++++++++++++++++-
 2 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/demo/src/main/kotlin/dev/hotwire/turbo/demo/main/MainSessionNavHostFragment.kt b/demo/src/main/kotlin/dev/hotwire/turbo/demo/main/MainSessionNavHostFragment.kt
index 0e470dc0..51109aaf 100644
--- a/demo/src/main/kotlin/dev/hotwire/turbo/demo/main/MainSessionNavHostFragment.kt
+++ b/demo/src/main/kotlin/dev/hotwire/turbo/demo/main/MainSessionNavHostFragment.kt
@@ -23,9 +23,6 @@ class MainSessionNavHostFragment : TurboSessionNavHostFragment() {
 
     override val startLocation = HOME_URL
 
-    override val registeredActivities: List<KClass<out AppCompatActivity>>
-        get() = listOf()
-
     override val registeredFragments: List<KClass<out Fragment>>
         get() = listOf(
             WebFragment::class,
diff --git a/turbo/src/main/kotlin/dev/hotwire/turbo/session/TurboSessionNavHostFragment.kt b/turbo/src/main/kotlin/dev/hotwire/turbo/session/TurboSessionNavHostFragment.kt
index 1ea5b1d2..1d89b982 100644
--- a/turbo/src/main/kotlin/dev/hotwire/turbo/session/TurboSessionNavHostFragment.kt
+++ b/turbo/src/main/kotlin/dev/hotwire/turbo/session/TurboSessionNavHostFragment.kt
@@ -13,12 +13,38 @@ import dev.hotwire.turbo.views.TurboWebView
 import kotlin.reflect.KClass
 
 abstract class TurboSessionNavHostFragment : NavHostFragment() {
+    /**
+     * The name of the [TurboSession] instance, which is helpful for debugging
+     * purposes. This is arbitrary, but must be unique in your app.
+     */
     abstract val sessionName: String
+
+    /**
+     * The url of a starting location when your app starts up.
+     */
     abstract val startLocation: String
+
+    /**
+     * The location of your [TurboPathConfiguration] JSON file(s) to configure
+     * navigation rules.
+     */
     abstract val pathConfigurationLocation: TurboPathConfiguration.Location
-    abstract val registeredActivities: List<KClass<out AppCompatActivity>>
+
+    /**
+     * A list of registered fragments that can be navigated to. Every possible
+     * [dev.hotwire.turbo.fragments.TurboFragment] destination must be listed here.
+     */
     abstract val registeredFragments: List<KClass<out Fragment>>
 
+    /**
+     * A list of registered Activities that can be navigated to. This is optional.
+     */
+    open val registeredActivities: List<KClass<out AppCompatActivity>> = emptyList()
+
+    /**
+     * The [TurboSession] instance that is shared with all destinations that are
+     * hosted inside this [TurboSessionNavHostFragment].
+     */
     lateinit var session: TurboSession
         private set
 
@@ -34,14 +60,29 @@ abstract class TurboSessionNavHostFragment : NavHostFragment() {
         onSessionCreated()
     }
 
+    /**
+     * Called whenever the [TurboSession] instance has been (re)created. A new
+     * session is created whenever the [TurboSessionNavHostFragment] is created
+     * and whenever the WebView render process has been terminated and a new
+     * WebView instance is required.
+     */
     open fun onSessionCreated() {
         session.pathConfiguration.load(pathConfigurationLocation)
     }
 
+    /**
+     * Called whenever a new WebView instance needs to be (re)created. You can
+     * override this to provide your own [TurboWebView] subclass if you need
+     * custom behaviors.
+     */
     open fun onCreateWebView(context: Context): TurboWebView {
         return TurboWebView(context, null)
     }
 
+    /**
+     * Resets the [TurboSessionNavHostFragment] instance, it's [TurboSession]
+     * instance, and the entire navigation graph to its original starting point.
+     */
     fun reset(onReset: () -> Unit = {}) {
         currentNavDestination.delegate().navigator.onNavigationVisit {
             currentNavDestination.clearBackStack {
@@ -57,6 +98,9 @@ abstract class TurboSessionNavHostFragment : NavHostFragment() {
         }
     }
 
+    /**
+     * Retrieves the currently active [TurboNavDestination] on the backstack.
+     */
     val currentNavDestination: TurboNavDestination
         get() = childFragmentManager.primaryNavigationFragment as TurboNavDestination?
             ?: throw IllegalStateException("No current destination found in NavHostFragment")