Merge "Add doc for AppListModel"

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>?
 }

packages/SettingsLib/SpaPrivileged/src/com/android/settingslib/spaprivileged/template/app/TogglePermissionAppList.kt

@@ -30,21 +30,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)
 }