ComposeMail - Add some comments to the paging implementation

Author: oscar-ad

demoProjects/ComposeMail/app/src/main/java/com/example/composemail/model/ComposeMailModel.kt

@@ -44,6 +44,7 @@ class ComposeMailModel(application: Application) : AndroidViewModel(application)
     val conversations: Flow<PagingData<MailEntryInfo>> = Pager(
         config = PagingConfig(
             pageSize = LOAD_LIMIT,
+            // Enable placeholders when loading indicators are supported, see MailItem.kt
             enablePlaceholders = true,
             prefetchDistance = REFRESH_THRESHOLD,
             initialLoadSize = LOAD_LIMIT

demoProjects/ComposeMail/app/src/main/java/com/example/composemail/model/paging/MailsSource.kt

@@ -33,6 +33,8 @@ class MailsSource(private val mailRepo: MailRepository) : PagingSource<Int, Mail
             data = nextMails.conversations,
             prevKey = if (nextPage == 0) null else nextMails.page - 1,
             nextKey = nextMails.page + 1,
+            // An additional item that will work as a loading placeholder
+            // while the next page is produced
             itemsAfter = 1
         )
     }

demoProjects/ComposeMail/app/src/main/java/com/example/composemail/ui/mails/MailItem.kt

@@ -57,22 +57,36 @@ import com.example.composemail.model.data.MailEntryInfo
 import com.example.composemail.ui.components.CheapText
 import com.example.composemail.ui.theme.textBackgroundColor
 
+/**
+ * Composable to display a mail entry, given by [MailEntryInfo].
+ *
+ * When [info] is null, it will display a loading indicator, if the info
+ * then changes to not-null it will animate the transition to show the info and
+ * dismiss the loading indicator.
+ *
+ * @see PreviewConversationLoading
+ */
 @Composable
 fun MailItem(
     modifier: Modifier = Modifier,
     state: MailItemState = MailItemState(-1) { _, _ -> },
     info: MailEntryInfo?
 ) {
-    val csTarget: MotionMailState =
+    // The layout (as a ConstraintSet ID) we want the Composable to take,
+    // MotionLayout will animate the transition to that layout
+    val targetState: MotionMailState =
         when {
+            // No info to display, show a Loading state
             info == null -> MotionMailState.Loading
+            // The item is selected, show as selected
             state.isSelected -> MotionMailState.Selected
+            // The 'normal' state that just displays the given info
             else -> MotionMailState.Normal
         }
     MotionLayoutMail(
         modifier = modifier,
         info = info ?: MailEntryInfo.Default,
-        targetState = csTarget,
+        targetState = targetState,
         onSelectedMail = {
             // Toggle selection
             state.setSelected(!state.isSelected)
@@ -82,6 +96,11 @@ fun MailItem(
 
 const val ANIMATION_DURATION: Int = 400
 
+/**
+ * An enum that represents the different layout states of the Composable.
+ *
+ * Each corresponds to a ConstraintSet in the MotionScene.
+ */
 enum class MotionMailState(val tag: String) {
     Loading("empty"),
     Normal("normal"),

demoProjects/ComposeMail/app/src/main/java/com/example/composemail/ui/mails/MailList.kt

@@ -34,17 +34,22 @@ fun MailList(
     listState: MailListState,
     observableConversations: Flow<PagingData<MailEntryInfo>>
 ) {
+    // The items provided through the model using Pager through a Flow
     val lazyMailItems: LazyPagingItems<MailEntryInfo> =
         observableConversations.collectAsLazyPagingItems()
 
     LazyColumn(
         modifier = modifier,
         verticalArrangement = Arrangement.spacedBy(4.dp)
     ) {
-        itemsIndexed(lazyMailItems) { _, mailItem ->
+        itemsIndexed(lazyMailItems) { _, mailInfo ->
+            // The Pager, configured with placeholders may initially provide
+            // a null mailInfo when it reaches the current end of the list,
+            // it will then provide a non-null mailInfo for the same Composable,
+            // MailItem animates the transition from those two values
             MailItem(
-                info = mailItem,
-                state = listState.stateFor(mailItem?.id)
+                info = mailInfo,
+                state = listState.stateFor(mailInfo?.id)
             )
         }
     }