From 586abf6b7b84dd4682fad3234b4822597db5d329 Mon Sep 17 00:00:00 2001
From: Chaohui Wang <chaohuiw@google.com>
Date: Tue, 6 Sep 2022 13:37:25 +0800
Subject: [PATCH] Add doc for AppListModel

Also for TogglePermissionAppListModel.

Bug: 235727273
Test: TAP
Change-Id: I955dc5b25c638bed3b4d9932fcd7e5768a03e987
---
 .../spaprivileged/model/app/AppListModel.kt   | 34 +++++++++++++++++++
 .../template/app/TogglePermissionAppList.kt   | 30 ++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/packages/SettingsLib/SpaPrivileged/src/com/android/settingslib/spaprivileged/model/app/AppListModel.kt b/packages/SettingsLib/SpaPrivileged/src/com/android/settingslib/spaprivileged/model/app/AppListModel.kt
index 00eb60b6ec7ac..373b57f73ef02 100644
--- a/packages/SettingsLib/SpaPrivileged/src/com/android/settingslib/spaprivileged/model/app/AppListModel.kt
+++ b/packages/SettingsLib/SpaPrivileged/src/com/android/settingslib/spaprivileged/model/app/AppListModel.kt
@@ -12,18 +12,52 @@ data class AppEntry<T : AppRecord>(
     val labelCollationKey: CollationKey,
 )
 
+/**
+ * Implement this interface to build an App List.
+ */
 interface AppListModel<T : AppRecord> {
+    /**
+     * Returns the spinner options available to the App List.
+     *
+     * Default no spinner will be shown.
+     */
     fun getSpinnerOptions(): List<String> = emptyList()
+
+    /**
+     * Loads the extra info for the App List, and generates the [AppRecord] List.
+     */
     fun transform(userIdFlow: Flow<Int>, appListFlow: Flow<List<ApplicationInfo>>): Flow<List<T>>
+
+    /**
+     * Filters the [AppRecord] list.
+     *
+     * @return the [AppRecord] list which will be displayed.
+     */
     fun filter(userIdFlow: Flow<Int>, option: Int, recordListFlow: Flow<List<T>>): Flow<List<T>>
 
+    /**
+     * This function is called when the App List's loading is finished and displayed to the user.
+     *
+     * Could do some pre-cache here.
+     */
     suspend fun onFirstLoaded(recordList: List<T>) {}
+
+    /**
+     * Gets the comparator to sort the App List.
+     *
+     * Default sorting is based on the app label.
+     */
     fun getComparator(option: Int): Comparator<AppEntry<T>> = compareBy(
         { it.labelCollationKey },
         { it.record.app.packageName },
         { it.record.app.uid },
     )
 
+    /**
+     * Gets the summary for the given app record.
+     *
+     * @return null if no summary should be displayed.
+     */
     @Composable
     fun getSummary(option: Int, record: T): State<String>?
 }
diff --git a/packages/SettingsLib/SpaPrivileged/src/com/android/settingslib/spaprivileged/template/app/TogglePermissionAppList.kt b/packages/SettingsLib/SpaPrivileged/src/com/android/settingslib/spaprivileged/template/app/TogglePermissionAppList.kt
index 3cc5854b95e40..9037f1db13279 100644
--- a/packages/SettingsLib/SpaPrivileged/src/com/android/settingslib/spaprivileged/template/app/TogglePermissionAppList.kt
+++ b/packages/SettingsLib/SpaPrivileged/src/com/android/settingslib/spaprivileged/template/app/TogglePermissionAppList.kt
@@ -29,21 +29,51 @@ import com.android.settingslib.spa.widget.preference.PreferenceModel
 import com.android.settingslib.spaprivileged.model.app.AppRecord
 import kotlinx.coroutines.flow.Flow
 
+/**
+ * Implement this interface to build an App List which toggles a permission on / off.
+ */
 interface TogglePermissionAppListModel<T : AppRecord> {
     val pageTitleResId: Int
     val switchTitleResId: Int
     val footerResId: Int
 
+    /**
+     * Loads the extra info for the App List, and generates the [AppRecord] List.
+     *
+     * Default is implemented by [transformItem]
+     */
     fun transform(userIdFlow: Flow<Int>, appListFlow: Flow<List<ApplicationInfo>>): Flow<List<T>> =
         appListFlow.asyncMapItem(::transformItem)
 
+    /**
+     * Loads the extra info for one app, and generates the [AppRecord].
+     *
+     * This must be implemented, because when show the App Info page for single app, this will be
+     * used instead of [transform].
+     */
     fun transformItem(app: ApplicationInfo): T
+
+    /**
+     * Filters the [AppRecord] list.
+     *
+     * @return the [AppRecord] list which will be displayed.
+     */
     fun filter(userIdFlow: Flow<Int>, recordListFlow: Flow<List<T>>): Flow<List<T>>
 
+    /**
+     * Gets whether the permission is allowed for the given app.
+     */
     @Composable
     fun isAllowed(record: T): State<Boolean?>
 
+    /**
+     * Gets whether the permission on / off is changeable for the given app.
+     */
     fun isChangeable(record: T): Boolean
+
+    /**
+     * Sets whether the permission is allowed for the given app.
+     */
     fun setAllowed(record: T, newAllowed: Boolean)
 }