Docs update[ feature/savingAccounts] MM-440 (#2998)

Author: Aryan-Baglane

feature/savings-account/src/commonMain/kotlin/org/mifos/mobile/feature/savingsaccount/components/SavingsActionItems.kt

@@ -26,34 +26,48 @@ import org.mifos.mobile.core.common.Constants
 import org.mifos.mobile.core.designsystem.icon.MifosIcons
 
 // TODO add some constants or enum class for routes and use
+/**
+ * A sealed class representing the distinct user-facing actions available for a savings account.
+ * Each action is defined as a `data object` and encapsulates UI-related metadata.
+ *
+ * This class is used to dynamically generate UI components, such as a list of action buttons or cards.
+ *
+ * @property title The string resource for the action's primary title.
+ * @property subTitle The string resource for the action's descriptive subtitle or tip.
+ * @property icon The [ImageVector] used to visually represent the action.
+ * @property route A unique string identifier used for navigation or logic handling related to the action.
+ */
 sealed class SavingsActionItems(
     val title: StringResource,
     val subTitle: StringResource,
     val icon: ImageVector,
     val route: String,
 ) {
-
+    /** Represents the action to initiate a money transfer from the account. */
     data object Transfer : SavingsActionItems(
         title = Res.string.feature_account_action_transfer,
         subTitle = Res.string.feature_account_action_transfer_tip,
         icon = MifosIcons.MoneyHand,
         route = Constants.TRANSFER,
     )
 
+    /** Represents the action to view the transaction history of the account. */
     data object Transactions : SavingsActionItems(
         title = Res.string.feature_account_action_transactions,
         subTitle = Res.string.feature_account_action_transactions_tip,
         icon = MifosIcons.ChatHistory,
         route = Constants.TRANSACTIONS,
     )
 
+    /** Represents the action to view any charges applied to the account. */
     data object Charges : SavingsActionItems(
         title = Res.string.feature_account_action_charges,
         subTitle = Res.string.feature_account_action_charges_tip,
         icon = MifosIcons.ReceiptMoney,
         route = Constants.CHARGES,
     )
 
+    /** Represents the action to display a QR code associated with the account for receiving payments. */
     data object QrCode : SavingsActionItems(
         title = Res.string.feature_account_action_qr,
         subTitle = Res.string.feature_account_action_qr_tip,
@@ -62,6 +76,10 @@ sealed class SavingsActionItems(
     )
 }
 
+/**
+ * An immutable list containing the standard set of actions available for a savings account.
+ * This list is used to populate UI elements that display all possible account actions in a predefined order.
+ */
 internal val savingsAccountActions: ImmutableList<SavingsActionItems> = persistentListOf(
     SavingsActionItems.Transfer,
     SavingsActionItems.Transactions,

feature/savings-account/src/commonMain/kotlin/org/mifos/mobile/feature/savingsaccount/di/SavingsAccountModule.kt

@@ -16,9 +16,32 @@ import org.mifos.mobile.feature.savingsaccount.savingsAccountDetails.SavingsAcco
 import org.mifos.mobile.feature.savingsaccount.savingsAccountUpdate.AccountUpdateViewModel
 import org.mifos.mobile.feature.savingsaccount.savingsAccountWithdraw.AccountWithdrawViewModel
 
+/**
+ * Koin module for providing dependencies related to the Savings Account feature.
+ *
+ * This module declares all the ViewModels used across the savings account screens,
+ * allowing Koin's dependency injection framework to construct and provide them where needed.
+ * The `viewModelOf` factory automatically handles the resolution of constructor dependencies for each ViewModel.
+ */
 val savingsAccountModule = module {
+    /**
+     * Provides an instance of [SavingsAccountViewmodel].
+     * This ViewModel is responsible for the main savings account list screen.
+     */
     viewModelOf(::SavingsAccountViewmodel)
+    /**
+     * Provides an instance of [SavingsAccountDetailsViewModel].
+     * This ViewModel manages the logic for the savings account details screen.
+     */
     viewModelOf(::SavingsAccountDetailsViewModel)
+    /**
+     * Provides an instance of [AccountUpdateViewModel].
+     * This ViewModel handles the logic for updating savings account details.
+     */
     viewModelOf(::AccountUpdateViewModel)
+    /**
+     * Provides an instance of [AccountWithdrawViewModel].
+     * This ViewModel is responsible for the account withdrawal screen logic.
+     */
     viewModelOf(::AccountWithdrawViewModel)
 }

feature/savings-account/src/commonMain/kotlin/org/mifos/mobile/feature/savingsaccount/navigation/SavingsNavigation.kt

@@ -24,12 +24,39 @@ import org.mifos.mobile.feature.savingsaccount.savingsAccountUpdate.navigateToSa
 import org.mifos.mobile.feature.savingsaccount.savingsAccountUpdate.savingsAccountUpdateDestination
 import org.mifos.mobile.feature.savingsaccount.savingsAccountWithdraw.savingsAccountWithdrawDestination
 
+/**
+ * A serializable, type-safe route representing the entry point for the nested
+ * savings account navigation graph.
+ */
 @Serializable
 data object SavingsGraphRoute
 
+/**
+ * Navigates to the savings account navigation graph.
+ *
+ * This is a convenience extension function on [NavController] that encapsulates the
+ * logic for navigating to the start of the savings account feature.
+ *
+ * @param navOptions Optional [NavOptions] to apply to this navigation operation.
+ */
 fun NavController.navigateToSavingsGraph(navOptions: NavOptions? = null) =
     navigate(SavingsAccountRoute, navOptions)
 
+/**
+ * Builds the nested navigation graph for the savings account feature.
+ *
+ * This function defines all the destinations within the savings account module and
+ * wires them together. It takes lambdas for navigating to screens both inside and
+ * outside of this feature's scope, promoting a decoupled architecture.
+ *
+ * @param navController The [NavController] used for handling navigation events within the graph.
+ * @param navigateToClientChargeScreen Lambda to navigate to the client charges screen.
+ * @param navigateToTransferScreen Lambda to navigate to the fund transfer screen.
+ * @param navigateToAuthenticateScreen Lambda to navigate to an authentication screen.
+ * @param navigateToStatusScreen Lambda to navigate to a generic status/result screen after an operation.
+ * @param navigateToSavingsAccountTransactionScreen Lambda to navigate to the transaction history screen.
+ * @param navigateToQrCodeScreen Lambda to navigate to the QR code display screen.
+ */
 fun NavGraphBuilder.savingsNavGraph(
     navController: NavController,
     navigateToClientChargeScreen: (String, Long) -> Unit,
@@ -42,25 +69,28 @@ fun NavGraphBuilder.savingsNavGraph(
     navigation<SavingsGraphRoute>(
         startDestination = SavingsAccountRoute,
     ) {
+        // Destination for the list of savings accounts
         savingsAccountDestination(
             navigateBack = navController::popBackStack,
         )
-
+        // Destination for the details of a single savings account
         savingsAccountDetailsDestination(
             navigateBack = navController::popBackStack,
             navigateToClientChargeScreen = navigateToClientChargeScreen,
-            navigateToUpdateScreen = navController::navigateToSavingsAccountUpdateScreen,
-            navigateToSavingsAccountTransactionScreen = navigateToSavingsAccountTransactionScreen,
+            navigateToUpdateScreen =
+            navController::navigateToSavingsAccountUpdateScreen,
+            navigateToSavingsAccountTransactionScreen =
+            navigateToSavingsAccountTransactionScreen,
             navigateToQrCodeScreen = navigateToQrCodeScreen,
             navigateToTransferScreen = navigateToTransferScreen,
         )
-
+        // Destination for updating a savings account (e.g., deposit)
         savingsAccountUpdateDestination(
             navigateBack = navController::popBackStack,
             navigateToStatusScreen = navigateToStatusScreen,
             navigateToAuthenticateScreen = navigateToAuthenticateScreen,
         )
-
+        // Destination for withdrawing from a savings account
         savingsAccountWithdrawDestination(
             navigateBack = navController::popBackStack,
             navigateToStatusScreen = navigateToStatusScreen,

feature/savings-account/src/commonMain/kotlin/org/mifos/mobile/feature/savingsaccount/savingsAccount/SavingsAccountNavigation.kt

@@ -17,12 +17,36 @@ import androidx.navigation.NavOptions
 import kotlinx.serialization.Serializable
 import org.mifos.mobile.core.ui.composableWithSlideTransitions
 
+/**
+ * A type-safe, serializable route for the main Savings Account list screen.
+ * This object serves as the unique identifier for this destination in the
+ * navigation graph, making navigation more robust and less error-prone.
+ */
 @Serializable
 data object SavingsAccountRoute
 
+/**
+ * Navigates to the main Savings Account list screen.
+ *
+ * This is an extension function on [NavController] that simplifies the process
+ * of navigating to the savings account list destination.
+ *
+ * @param navOptions Optional [NavOptions] to apply to this navigation operation,
+ *   allowing for customization of transition animations or back stack behavior.
+ */
 fun NavController.navigateToSavingsAccountScreen(navOptions: NavOptions? = null) =
     navigate(SavingsAccountRoute, navOptions)
 
+/**
+ * Defines the composable destination for the "Savings Account" list screen
+ * within the navigation graph.
+ *
+ * This function sets up the route and the content to be displayed (`SavingsAccountScreen`),
+ * along with specifying the screen enter/exit transitions.
+ *
+ * @param navigateBack A lambda function to be invoked when the user initiates a
+ *   back action from the [SavingsAccountScreen].
+ */
 fun NavGraphBuilder.savingsAccountDestination(
     navigateBack: () -> Unit,
 ) {

feature/savings-account/src/commonMain/kotlin/org/mifos/mobile/feature/savingsaccount/savingsAccount/SavingsAccountScreen.kt

@@ -62,6 +62,22 @@ import org.mifos.mobile.core.ui.component.MifosProgressIndicator
 import org.mifos.mobile.core.ui.utils.EventsEffect
 import org.mifos.mobile.core.ui.utils.ScreenUiState
 
+/**
+ * A stateful composable that serves as the main entry point for the Savings Account list screen.
+ *
+ * This screen is responsible for observing state from the [SavingsAccountViewmodel], handling
+ * user events, and orchestrating the display of the savings account data. It also manages
+ * data loading triggers, including initial launch and external refresh signals.
+ *
+ * @param navigateBack A lambda to handle the back navigation event.
+ * @param onAccountClicked A callback invoked when a savings account item is clicked, providing the account type and ID.
+ * @param refreshSignal A signal to trigger a data refresh when its value changes.
+ * @param onLoadingCompleted A callback invoked when the data loading process finishes.
+ * @param accountTypeFilters A list of string resources representing the applied account type filters.
+ * @param accountStatusFilters A list of string resources representing the applied account status filters.
+ * @param filtersClicked A lambda to handle the click event on the filter icon.
+ * @param viewModel The [SavingsAccountViewmodel] instance for this screen, typically provided by Koin.
+ */
 @Composable
 fun SavingsAccountScreen(
     navigateBack: () -> Unit,
@@ -110,6 +126,13 @@ fun SavingsAccountScreen(
     )
 }
 
+/**
+ * A composable responsible for displaying dialogs based on the [SavingsAccountState].
+ * Currently, it handles the display of an error dialog with a retry option.
+ *
+ * @param dialogState The current state of the dialog from [SavingsAccountState].
+ * @param onAction A callback to send actions, like retry, to the ViewModel.
+ */
 @Composable
 internal fun SavingsAccountDialog(
     dialogState: SavingsAccountState.DialogState?,
@@ -127,6 +150,16 @@ internal fun SavingsAccountDialog(
     }
 }
 
+/**
+ * A stateless composable that renders the main UI for the Savings Account screen.
+ *
+ * It conditionally displays UI elements based on the [ScreenUiState], such as a loading
+ * indicator, error messages, an empty data view, or the success view with the list of accounts.
+ *
+ * @param state The current [SavingsAccountState] to render.
+ * @param onAction A callback to send user actions to the ViewModel.
+ * @param filtersClicked A lambda to handle the click event on the filter icon.
+ */
 @Composable
 internal fun SavingsAccountContent(
     state: SavingsAccountState,
@@ -289,6 +322,13 @@ internal fun SavingsAccountContent(
     }
 }
 
+/**
+ * A Jetpack Compose preview for the [SavingsAccountContent].
+ *
+ * This provides a design-time visualization of the savings account screen UI in
+ * Android Studio, configured with a default empty state.
+ */
+
 @Preview
 @Composable
 private fun Savings_Account_Preview() {

feature/savings-account/src/commonMain/kotlin/org/mifos/mobile/feature/savingsaccount/savingsAccountDetails/SavingsAccountDetailsNavigation.kt

@@ -21,14 +21,40 @@ import org.mifos.mobile.core.model.entity.AccountDetails
 import org.mifos.mobile.core.model.enums.TransferType
 import org.mifos.mobile.core.ui.composableWithSlideTransitions
 
+/**
+ * Type-safe, serializable route for the Savings Account Details screen.
+ *
+ * @property accountId The unique ID of the savings account to display.
+ */
 @Serializable
 data class SavingsAccountDetailsRoute(
     val accountId: Long,
 )
 
-fun NavController.navigateToSavingsAccountDetailsScreen(accountId: Long, navOptions: NavOptions? = null) =
+/**
+ * Navigates to the Savings Account Details screen.
+ *
+ * @param accountId The ID of the savings account.
+ * @param navOptions Optional navigation options.
+ */
+
+fun NavController.navigateToSavingsAccountDetailsScreen(
+    accountId: Long,
+    navOptions: NavOptions? = null,
+) =
     navigate(SavingsAccountDetailsRoute(accountId), navOptions)
 
+/**
+ * Defines the composable destination for the "Savings Account Details" screen.
+ * This sets up the route, content, and navigation callbacks.
+ *
+ * @param navigateBack Handles back navigation.
+ * @param navigateToTransferScreen Navigates to the fund transfer screen.
+ * @param navigateToClientChargeScreen Navigates to the account charges screen.
+ * @param navigateToUpdateScreen Navigates to the account update screen.
+ * @param navigateToSavingsAccountTransactionScreen Navigates to the transaction history.
+ * @param navigateToQrCodeScreen Navigates to the QR code display screen.
+ */
 fun NavGraphBuilder.savingsAccountDetailsDestination(
     navigateBack: () -> Unit,
     navigateToTransferScreen: (AccountDetails) -> Unit,