documentation update for the feature/application

Author: Aryan-Baglane

feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/di/SavingsApplicationModule.kt

@@ -14,7 +14,21 @@ import org.koin.dsl.module
 import org.mifos.mobile.feature.savings.application.fillApplication.SavingsFillApplicationViewModel
 import org.mifos.mobile.feature.savings.application.savingsApplication.SavingsApplyViewModel
 
+/**
+ * Koin module for providing dependencies related to the Savings Application feature.
+ *
+ * This module declares the ViewModels used in the savings account application process,
+ * allowing Koin's dependency injection framework to construct and provide them where needed.
+ */
 val savingsApplicationModule = module {
+    /**
+     * Provides an instance of [SavingsApplyViewModel].
+     * This ViewModel manages the logic for the initial savings application screen.
+     */
     viewModelOf(::SavingsApplyViewModel)
+    /**
+     * Provides an instance of [SavingsFillApplicationViewModel].
+     * This ViewModel handles the logic for filling out the details of a new savings application.
+     */
     viewModelOf(::SavingsFillApplicationViewModel)
 }

feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationRoute.kt

@@ -17,13 +17,35 @@ import androidx.navigation.NavOptions
 import kotlinx.serialization.Serializable
 import org.mifos.mobile.core.ui.composableWithSlideTransitions
 
+/**
+ * A type-safe, serializable route for the "Fill Savings Application" screen.
+ *
+ * This class encapsulates the necessary parameters required to fill out a new
+ * savings account application, ensuring robust and error-free navigation.
+ *
+ * @property savingsProductId The unique identifier of the selected savings product.
+ * @property fieldOfficerId The unique identifier of the assigned field officer.
+ * @property fieldOfficerName The name of the assigned field officer.
+ */
 @Serializable
 data class SavingsFillApplicationRoute(
     val savingsProductId: Long,
     val fieldOfficerId: Long,
     val fieldOfficerName: String,
 )
 
+/**
+ * Navigates to the "Fill Savings Application" screen.
+ *
+ * This is an extension function on [NavController] that simplifies the process
+ * of navigating to the application form by constructing and passing the
+ * [SavingsFillApplicationRoute] with the required product and officer details.
+ *
+ * @param savingsProductId The ID of the savings product.
+ * @param fieldOfficerId The ID of the field officer.
+ * @param fieldOfficerName The name of the field officer.
+ * @param navOptions Optional [NavOptions] to apply to this navigation operation.
+ */
 fun NavController.navigateToSavingsFillApplicationScreen(
     savingsProductId: Long,
     fieldOfficerId: Long,
@@ -33,6 +55,20 @@ fun NavController.navigateToSavingsFillApplicationScreen(
     this.navigate(SavingsFillApplicationRoute(savingsProductId, fieldOfficerId, fieldOfficerName), navOptions)
 }
 
+
+/**
+ * Defines the composable destination for the "Fill Savings Application" screen
+ * within the navigation graph.
+ *
+ * This function sets up the route and the screen content (`SavingsFillApplicationScreen`),
+ * and wires up the necessary navigation callbacks for actions initiated from the screen.
+ *
+ * @param navigateToAuthenticateScreen A lambda to navigate to an authentication screen,
+ *   typically required before submitting the application.
+ * @param navigateToStatusScreen A lambda to navigate to a generic status/result screen
+ *   after the application submission is complete.
+ * @param navigateBack A lambda function to handle the back navigation event.
+ */
 fun NavGraphBuilder.savingsFillApplicationDestination(
     navigateToAuthenticateScreen: () -> Unit,
     navigateToStatusScreen: (String, String, String, String, String) -> Unit,

feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationScreen.kt

@@ -63,6 +63,17 @@ import org.mifos.mobile.core.ui.component.MifosProgressIndicatorOverlay
 import org.mifos.mobile.core.ui.utils.EventsEffect
 import org.mifos.mobile.core.ui.utils.ScreenUiState
 
+/**
+ * A stateful composable serving as the entry point for the "Fill Savings Application" screen.
+ *
+ * This function connects to the [SavingsFillApplicationViewModel] to observe state, handle UI
+ * events, and orchestrate navigation based on user actions and ViewModel commands.
+ *
+ * @param navigateBack A lambda to handle the back navigation event.
+ * @param navigateToStatusScreen A lambda to navigate to a generic status screen after an operation.
+ * @param navigateToAuthenticateScreen A lambda to navigate to an authentication screen for sensitive actions.
+ * @param viewModel The ViewModel responsible for the screen's logic and state.
+ */
 @Composable
 internal fun SavingsFillApplicationScreen(
     navigateBack: () -> Unit,
@@ -106,6 +117,16 @@ internal fun SavingsFillApplicationScreen(
     )
 }
 
+/**
+ * A composable responsible for displaying dialogs based on the [SavingsApplicationDialogState].
+ *
+ * This function handles the presentation of error dialogs and confirmation dialogs
+ * for unsaved changes.
+ *
+ * @param state The current [SavingsApplicationState] used for context like network status.
+ * @param dialogState The current state of the dialog to be displayed.
+ * @param onAction A callback to send actions (like dismiss or confirm) to the ViewModel.
+ */
 @Composable
 internal fun SavingsFillApplicationDialog(
     state: SavingsApplicationState,
@@ -135,6 +156,16 @@ internal fun SavingsFillApplicationDialog(
     }
 }
 
+/**
+ * A stateless composable that renders the main UI for the "Fill Savings Application" screen.
+ *
+ * It conditionally displays UI based on the [ScreenUiState] (e.g., loading, error, success).
+ * The success state includes a form with various input fields for the application details.
+ *
+ * @param state The current [SavingsApplicationState] to render.
+ * @param onAction A callback to send user actions to the ViewModel.
+ * @param modifier The [Modifier] to be applied to the layout.
+ */
 @Composable
 internal fun SavingsFillApplicationContent(
     state: SavingsApplicationState,

feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/navigation/SavingsApplicationNavGraph.kt

@@ -19,13 +19,38 @@ import org.mifos.mobile.feature.savings.application.fillApplication.savingsFillA
 import org.mifos.mobile.feature.savings.application.savingsApplication.SavingsApplyRoute
 import org.mifos.mobile.feature.savings.application.savingsApplication.savingsApplyDestination
 
+/**
+ * A type-safe, serializable object representing the route for the nested
+ * Savings Application navigation graph.
+ */
 @Serializable
 data object SavingsApplicationNavGraph
 
+/**
+ * Navigates to the Savings Application navigation graph.
+ *
+ * This is a convenience extension function on [NavController] that encapsulates
+ * the logic for navigating to the start of the savings application feature.
+ *
+ * @param navOptions Optional [NavOptions] to apply to this navigation operation.
+ */
 fun NavController.navigateToSavingsApplicationGraph(navOptions: NavOptions? = null) {
     this.navigate(SavingsApplicationNavGraph, navOptions)
 }
 
+/**
+ * Builds the nested navigation graph for the savings account application feature.
+ *
+ * This function defines all the destinations within the savings application module
+ * (product selection and form filling) and wires them together. It promotes a
+ * decoupled architecture by accepting lambdas for navigation to external screens.
+ *
+ * @param navController The [NavController] used for handling navigation events within the graph.
+ * @param navigateToAuthenticateScreen Lambda to navigate to an authentication screen,
+ *   required before submitting the application.
+ * @param navigateToStatusScreen Lambda to navigate to a generic status/result screen
+ *   after the application submission is complete.
+ */
 fun NavGraphBuilder.savingsApplicationNavGraph(
     navController: NavController,
     navigateToAuthenticateScreen: () -> Unit,

feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyRoute.kt

@@ -15,14 +15,38 @@ import androidx.navigation.NavOptions
 import kotlinx.serialization.Serializable
 import org.mifos.mobile.core.ui.composableWithSlideTransitions
 
+/**
+ * A type-safe, serializable object representing the route for the initial
+ * "Apply for Savings Account" screen. This serves as the entry point for
+ * the savings application flow.
+ */
 @Serializable
 data object SavingsApplyRoute
 
+/**
+ * Navigates to the "Apply for Savings Account" screen.
+ *
+ * This is an extension function on [NavController] that simplifies navigating
+ * to the savings product selection screen.
+ *
+ * @param navOptions Optional [NavOptions] to apply to this navigation operation.
+ */
 fun NavController.navigateToSavingsApplyScreen(
     navOptions: NavOptions? = null,
 ) =
     navigate(SavingsApplyRoute, navOptions)
 
+/**
+ * Defines the composable destination for the "Apply for Savings Account" screen
+ * within the navigation graph.
+ *
+ * This function sets up the route, the screen content (`SavingsApplyScreen`),
+ * and wires up the navigation callbacks for actions initiated from this screen.
+ *
+ * @param navigateToFillDetailsScreen A lambda to navigate to the application form screen,
+ *   passing the selected product ID, officer ID, and officer name.
+ * @param navigateBack A lambda function to handle the back navigation event.
+ */
 fun NavGraphBuilder.savingsApplyDestination(
     navigateToFillDetailsScreen: (Long, Long, String) -> Unit,
     navigateBack: () -> Unit,

feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyScreen.kt

@@ -51,6 +51,18 @@ import org.mifos.mobile.core.ui.component.MifosProgressIndicatorOverlay
 import org.mifos.mobile.core.ui.utils.EventsEffect
 import org.mifos.mobile.core.ui.utils.ScreenUiState
 
+/**
+ * A stateful composable that serves as the entry point for the "Apply for Savings" screen.
+ *
+ * This function connects to the [SavingsApplyViewModel] to observe UI state and handle
+ * one-time events. It is responsible for orchestrating navigation to the next step
+ * in the application process.
+ *
+ * @param navigateBack A lambda function to handle back navigation events.
+ * @param navigateToFillDetailsScreen A lambda to navigate to the detailed application form,
+ *   passing product and officer information.
+ * @param viewModel The ViewModel responsible for the screen's logic and state.
+ */
 @Composable
 internal fun SavingsApplyScreen(
     navigateBack: () -> Unit,
@@ -87,6 +99,15 @@ internal fun SavingsApplyScreen(
     )
 }
 
+/**
+ * A composable responsible for displaying dialogs based on the [SavingsApplicationDialogState].
+ *
+ * This function handles the presentation of error dialogs and confirmation dialogs
+ * for unsaved changes.
+ *
+ * @param dialogState The current state of the dialog to be displayed.
+ * @param onAction A callback to send actions (like dismiss or confirm) to the ViewModel.
+ */
 @Composable
 internal fun SavingsAccountDialog(
     dialogState: SavingsApplicationDialogState?,
@@ -114,6 +135,17 @@ internal fun SavingsAccountDialog(
     }
 }
 
+
+/**
+ * A stateless composable that renders the main UI for the "Apply for Savings" screen.
+ *
+ * It conditionally displays UI based on the [ScreenUiState] (e.g., loading, error, success).
+ * The success state includes dropdowns for selecting a savings product and a field officer.
+ *
+ * @param state The current [SavingsApplicationState] to render.
+ * @param onAction A callback to send user actions to the ViewModel.
+ * @param modifier The [Modifier] to be applied to the layout.
+ */
 @Composable
 internal fun SavingsAccountContent(
     state: SavingsApplicationState,