Documentation Done for feature/notification (#2991)

Author: WizCoderr

feature/notification/src/commonMain/kotlin/org/mifos/mobile/feature/notification/NotificationScreen.kt

@@ -51,6 +51,17 @@ import org.mifos.mobile.core.ui.component.EmptyDataView
 import org.mifos.mobile.core.ui.component.MifosErrorComponent
 import org.mifos.mobile.core.ui.component.MifosProgressIndicatorOverlay
 
+/**
+ * This is the main entry point for the Notification Screen feature. It's a composable function
+ * that sets up the screen, observes state from the [NotificationViewModel], and delegates the UI
+ * rendering to other composable functions.
+ *
+ * @param navigateBack A lambda function to be invoked when the user wants to navigate back from
+ *   this screen.
+ * @param modifier The [Modifier] to be applied to this composable.
+ * @param viewModel An instance of [NotificationViewModel] which holds the business logic for this
+ *   screen. It's provided by Koin's `koinViewModel()`.
+ */
 @Composable
 internal fun NotificationScreen(
     navigateBack: () -> Unit,
@@ -73,6 +84,22 @@ internal fun NotificationScreen(
     )
 }
 
+/**
+ * This composable function is responsible for displaying the main content of the Notification
+ * Screen. It acts as a presentation layer that reacts to different UI states like Loading, Error,
+ * Success, or Empty. Based on the `uiState`, it renders the appropriate composable.
+ *
+ * @param uiState The current state of the UI, which determines what to display.
+ * @param isNetworkAvailable A boolean that indicates whether the device has an active network
+ *   connection.
+ * @param navigateBack A lambda function to handle the back navigation event.
+ * @param onRetry A lambda function to be called when the user wants to retry loading notifications
+ *   after an error.
+ * @param dismissNotification A lambda function to handle the dismissal of a notification.
+ * @param isRefreshing A boolean that indicates if the screen is currently in a refresh state.
+ * @param onRefresh A lambda function to be called to refresh the list of notifications.
+ * @param modifier The [Modifier] to be applied to this composable.
+ */
 @Composable
 private fun NotificationScreen(
     uiState: NotificationUiState,
@@ -124,6 +151,19 @@ private fun NotificationScreen(
     )
 }
 
+/**
+ * This composable function is responsible for displaying the list of notifications. It uses a
+ * [PullToRefreshBox], allowing the user to swipe down to refresh the list. The actual list is
+ * rendered using a `LazyColumn` for efficient display of potentially long lists.
+ *
+ * @param isRefreshing A boolean indicating if the pull-to-refresh action is currently active.
+ * @param notifications The list of [MifosNotification] objects to be displayed.
+ * @param dismissNotification A lambda function that handles the action of dismissing a
+ *   notification.
+ * @param onRefresh A lambda function that's triggered when the user performs a pull-to-refresh
+ *   gesture.
+ * @param modifier The [Modifier] to be applied to this composable.
+ */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 private fun NotificationContent(
@@ -155,6 +195,16 @@ private fun NotificationContent(
     }
 }
 
+/**
+ * This composable function is designed to display a single notification item in the list. It shows
+ * the notification's message, the timestamp, and provides an "OK" button to dismiss it if it's
+ * unread. The visual style of the item changes based on whether the notification has been read.
+ *
+ * @param notification The [MifosNotification] object to be displayed.
+ * @param dismissNotification A lambda function that's called when the user dismisses the
+ *   notification.
+ * @param modifier The [Modifier] to be applied to this composable.
+ */
 @Composable
 private fun NotificationItem(
     notification: MifosNotification,

feature/notification/src/commonMain/kotlin/org/mifos/mobile/feature/notification/NotificationViewModel.kt

@@ -23,6 +23,17 @@ import org.mifos.mobile.core.data.util.NetworkMonitor
 import org.mifos.mobile.core.model.entity.MifosNotification
 import org.mifos.mobile.feature.notification.NotificationUiState.Loading
 
+/**
+ * The ViewModel for the Notification screen.
+ *
+ * This class is responsible for the business logic of the Notification screen. It fetches
+ * notifications from the [NotificationRepository], manages the UI state, and handles user
+ * interactions like refreshing the list and dismissing notifications. It's also aware of the
+ * network status, thanks to [NetworkMonitor].
+ *
+ * @param notificationRepositoryImp The repository that provides access to notification data.
+ * @param networkMonitor A utility to monitor the device's network connectivity.
+ */
 internal class NotificationViewModel(
     private val notificationRepositoryImp: NotificationRepository,
     networkMonitor: NetworkMonitor,
@@ -48,6 +59,10 @@ internal class NotificationViewModel(
         }
     }
 
+    /**
+     * Kicks off the process of loading notifications from the repository. This function updates the
+     * UI state to reflect the current status of the operation, such as Loading, Success, or Error.
+     */
     fun loadNotifications() {
         _notificationUiState.value = Loading
         viewModelScope.launch {
@@ -78,18 +93,36 @@ internal class NotificationViewModel(
         }
     }
 
+    /**
+     * Initiates a refresh of the notifications. This is typically triggered by a user action, like
+     * a pull-to-refresh gesture. It sets the refreshing state and then calls [loadNotifications]
+     * to fetch the latest data.
+     */
     fun refreshNotifications() {
         _isRefreshing.value = true
         loadNotifications()
     }
 
+    /**
+     * Marks a specific notification as read. This involves updating the notification's state in
+     * the local repository to ensure the change is persisted.
+     *
+     * @param notification The [MifosNotification] to be marked as read.
+     */
     fun dismissNotification(notification: MifosNotification) {
         viewModelScope.launch {
             notificationRepositoryImp.saveNotification(notification.copy(read = true))
             notificationRepositoryImp.updateReadStatus(notification, true)
         }
     }
 
+    /**
+     * Sorts a list of notifications. The sorting logic prioritizes unread notifications and then
+     * sorts them by timestamp, so the most recent ones appear first.
+     *
+     * @param notifications The list of [MifosNotification]s to be sorted.
+     * @return A new list containing the sorted notifications.
+     */
     private fun sortNotifications(notifications: List<MifosNotification>): List<MifosNotification> {
         return notifications.sortedWith(
             compareByDescending<MifosNotification> { !it.isRead() }
@@ -98,9 +131,34 @@ internal class NotificationViewModel(
     }
 }
 
+/**
+ * A sealed interface that represents the various states the Notification screen can be in. This
+ * allows for exhaustive state handling in the UI, ensuring a predictable user experience.
+ */
 internal sealed interface NotificationUiState {
+    /**
+     * Indicates that the notifications are currently being loaded. This is the ideal time to show
+     * a progress indicator.
+     */
     data object Loading : NotificationUiState
+
+    /**
+     * Represents a successful fetch of notifications.
+     *
+     * @param notifications The list of notifications to be displayed on the screen.
+     */
     data class Success(val notifications: List<MifosNotification>) : NotificationUiState
+
+    /**
+     * Signals that an error occurred while trying to fetch notifications.
+     *
+     * @param errorMessage A descriptive message about the error that can be shown to the user.
+     */
     data class Error(val errorMessage: String?) : NotificationUiState
+
+    /**
+     * Used when the notification list is empty. This state allows for showing a user-friendly
+     * message indicating that there are no notifications.
+     */
     data object Empty : NotificationUiState
 }

feature/notification/src/commonMain/kotlin/org/mifos/mobile/feature/notification/navigation/NotificationNavigation.kt

@@ -18,13 +18,32 @@ import kotlinx.serialization.Serializable
 import org.mifos.mobile.core.ui.composableWithPushTransitions
 import org.mifos.mobile.feature.notification.NotificationScreen
 
+/**
+ * A type-safe navigation destination for the Notification Screen. Using a serializable object
+ * like this ensures that navigation is robust and less prone to runtime errors.
+ */
 @Serializable
 data object NotificationRoute
 
+/**
+ * An extension function on [NavController] that provides a convenient and type-safe way to
+ * navigate to the Notification Screen.
+ *
+ * @param navOptions Optional [NavOptions] to apply to this navigation action. This can be used
+ *   to control aspects like the back stack and animations.
+ */
 fun NavController.navigateToNotificationScreen(navOptions: NavOptions? = null) {
     navigate(NotificationRoute, navOptions)
 }
 
+/**
+ * An extension function on [NavGraphBuilder] that defines the Notification Screen destination
+ * within the navigation graph. This is where the screen's composable is associated with its
+ * route, and where transitions and arguments can be configured.
+ *
+ * @param navigateBack A lambda function that will be invoked when the user navigates back from
+ *   the Notification Screen. This is typically used to pop the back stack.
+ */
 fun NavGraphBuilder.notificationDestination(
     navigateBack: () -> Unit,
 ) {