Add kdoc for immutable data structure classes.

In addition to the existing Immutable.md.

Bug: 285432076
Test: presubmit
Change-Id: I77529bb4782db6cbe7b8a8f96890a78661aa9fc0

9 files changed, 85 insertions, 0 deletions

diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedList.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedList.kt
index 6108ad298800..ce4aa4446698 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedList.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedList.kt
@@ -16,6 +16,9 @@
 
 package com.android.server.permission.access.immutable
 
+/**
+ * Immutable list with index-based access.
+ */
 sealed class IndexedList<T>(
     internal val list: ArrayList<T>
 ) : Immutable<MutableIndexedList<T>> {
@@ -34,6 +37,9 @@ sealed class IndexedList<T>(
     override fun toString(): String = list.toString()
 }
 
+/**
+ * Mutable list with index-based access.
+ */
 class MutableIndexedList<T>(
     list: ArrayList<T> = ArrayList()
 ) : IndexedList<T>(list) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedListSet.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedListSet.kt
index 1202c817d97b..77e71baf0ab7 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedListSet.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedListSet.kt
@@ -16,6 +16,9 @@
 
 package com.android.server.permission.access.immutable
 
+/**
+ * Immutable set with index-based access, implemented using a list.
+ */
 sealed class IndexedListSet<T>(
     internal val list: ArrayList<T>
 ) : Immutable<MutableIndexedListSet<T>> {
@@ -36,6 +39,9 @@ sealed class IndexedListSet<T>(
     override fun toString(): String = list.toString()
 }
 
+/**
+ * Mutable set with index-based access, implemented using a list.
+ */
 class MutableIndexedListSet<T>(
     list: ArrayList<T> = ArrayList()
 ) : IndexedListSet<T>(list) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedMap.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedMap.kt
index 5c75de83792f..299cc89d9a07 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedMap.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedMap.kt
@@ -18,6 +18,9 @@ package com.android.server.permission.access.immutable
 
 import android.util.ArrayMap
 
+/**
+ * Immutable map with index-based access.
+ */
 sealed class IndexedMap<K, V>(
     internal val map: ArrayMap<K, V>
 ) : Immutable<MutableIndexedMap<K, V>> {
@@ -42,6 +45,9 @@ sealed class IndexedMap<K, V>(
     override fun toString(): String = map.toString()
 }
 
+/**
+ * Mutable map with index-based access.
+ */
 class MutableIndexedMap<K, V>(
     map: ArrayMap<K, V> = ArrayMap()
 ) : IndexedMap<K, V>(map) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedReferenceMap.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedReferenceMap.kt
index 8c963aae1967..ff76a4745c8b 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedReferenceMap.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedReferenceMap.kt
@@ -18,6 +18,11 @@ package com.android.server.permission.access.immutable
 
 import android.util.ArrayMap
 
+/**
+ * Immutable map with index-based access and mutable data structure values.
+ *
+ * @see MutableReference
+ */
 sealed class IndexedReferenceMap<K, I : Immutable<M>, M : I>(
     internal val map: ArrayMap<K, MutableReference<I, M>>
 ) : Immutable<MutableIndexedReferenceMap<K, I, M>> {
@@ -42,6 +47,11 @@ sealed class IndexedReferenceMap<K, I : Immutable<M>, M : I>(
     override fun toString(): String = map.toString()
 }
 
+/**
+ * Mutable map with index-based access and mutable data structure values.
+ *
+ * @see MutableReference
+ */
 class MutableIndexedReferenceMap<K, I : Immutable<M>, M : I>(
     map: ArrayMap<K, MutableReference<I, M>> = ArrayMap()
 ) : IndexedReferenceMap<K, I, M>(map) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedSet.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedSet.kt
index 986861624e4b..547e56cef62a 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedSet.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedSet.kt
@@ -18,6 +18,9 @@ package com.android.server.permission.access.immutable
 
 import android.util.ArraySet
 
+/**
+ * Immutable set with index-based access.
+ */
 sealed class IndexedSet<T>(
     internal val set: ArraySet<T>
 ) : Immutable<MutableIndexedSet<T>> {
@@ -37,6 +40,9 @@ sealed class IndexedSet<T>(
     override fun toString(): String = set.toString()
 }
 
+/**
+ * Mutable set with index-based access.
+ */
 class MutableIndexedSet<T>(
     set: ArraySet<T> = ArraySet()
 ) : IndexedSet<T>(set) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IntMap.kt b/services/permission/java/com/android/server/permission/access/immutable/IntMap.kt
index b7d8b4ccddd0..7ed29e8813ac 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IntMap.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IntMap.kt
@@ -18,6 +18,9 @@ package com.android.server.permission.access.immutable
 
 import android.util.SparseArray
 
+/**
+ * Immutable map with index-based access and [Int] keys.
+ */
 sealed class IntMap<T>(
     internal val array: SparseArray<T>
 ) : Immutable<MutableIntMap<T>> {
@@ -41,6 +44,9 @@ sealed class IntMap<T>(
     override fun toString(): String = array.toString()
 }
 
+/**
+ * Mutable map with index-based access and [Int] keys.
+ */
 class MutableIntMap<T>(
     array: SparseArray<T> = SparseArray()
 ) : IntMap<T>(array) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IntReferenceMap.kt b/services/permission/java/com/android/server/permission/access/immutable/IntReferenceMap.kt
index 22fa8f2a7c7e..160b2279a0ba 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IntReferenceMap.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IntReferenceMap.kt
@@ -18,6 +18,11 @@ package com.android.server.permission.access.immutable
 
 import android.util.SparseArray
 
+/**
+ * Immutable map with index-based access, [Int] keys and mutable data structure values.
+ *
+ * @see MutableReference
+ */
 sealed class IntReferenceMap<I : Immutable<M>, M : I>(
     internal val array: SparseArray<MutableReference<I, M>>
 ) : Immutable<MutableIntReferenceMap<I, M>> {
@@ -42,6 +47,11 @@ sealed class IntReferenceMap<I : Immutable<M>, M : I>(
     override fun toString(): String = array.toString()
 }
 
+/**
+ * Mutable map with index-based access, [Int] keys and mutable data structure values.
+ *
+ * @see MutableReference
+ */
 class MutableIntReferenceMap<I : Immutable<M>, M : I>(
     array: SparseArray<MutableReference<I, M>> = SparseArray()
 ) : IntReferenceMap<I, M>(array) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IntSet.kt b/services/permission/java/com/android/server/permission/access/immutable/IntSet.kt
index 9da36717db7e..21f2af20c3a9 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IntSet.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IntSet.kt
@@ -18,6 +18,9 @@ package com.android.server.permission.access.immutable
 
 import android.util.SparseBooleanArray
 
+/**
+ * Immutable set with index-based access and [Int] elements.
+ */
 sealed class IntSet(
     internal val array: SparseBooleanArray
 ) : Immutable<MutableIntSet> {
@@ -37,6 +40,9 @@ sealed class IntSet(
     override fun toString(): String = array.toString()
 }
 
+/**
+ * Mutable set with index-based access and [Int] elements.
+ */
 class MutableIntSet(
     array: SparseBooleanArray = SparseBooleanArray()
 ) : IntSet(array) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/MutableReference.kt b/services/permission/java/com/android/server/permission/access/immutable/MutableReference.kt
index e39a3bbc8942..171cfeb4379d 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/MutableReference.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/MutableReference.kt
@@ -16,14 +16,39 @@
 
 package com.android.server.permission.access.immutable
 
+/**
+ * Wrapper class for reference to a mutable data structure instance.
+ *
+ * This class encapsulates the logic to mutate/copy a mutable data structure instance and update the
+ * reference to the new mutated instance. It also remembers the mutated instance so that it can be
+ * reused during further mutations.
+ *
+ * Instances of this class should be kept private within a data structure, with the [get] method
+ * exposed on the immutable interface of the data structure as a `getFoo` method, and the [mutate]
+ * method exposed on the mutable interface of the data structure as a `mutateFoo` method. When the
+ * data structure is mutated/copied, a new instance of this class should be obtained with
+ * [toImmutable], which makes the wrapped reference immutable-only again and thus prevents
+ * further modifications to a data structure accessed with its immutable interface.
+ *
+ * @see MutableIndexedReferenceMap
+ * @see MutableIntReferenceMap
+ */
 class MutableReference<I : Immutable<M>, M : I> private constructor(
     private var immutable: I,
     private var mutable: M?
 ) {
     constructor(mutable: M) : this(mutable, mutable)
 
+    /**
+     * Return an immutable reference to the wrapped mutable data structure.
+     */
     fun get(): I = immutable
 
+    /**
+     * Make the wrapped mutable data structure mutable, by either calling [Immutable.toMutable] and
+     * replacing the wrapped reference with its result, or reusing the existing reference if it's
+     * already mutable.
+     */
     fun mutate(): M {
         mutable?.let { return it }
         return immutable.toMutable().also {
@@ -32,6 +57,10 @@ class MutableReference<I : Immutable<M>, M : I> private constructor(
         }
     }
 
+    /**
+     * Create a new [MutableReference] instance with the wrapped mutable data structure being
+     * immutable-only again.
+     */
     fun toImmutable(): MutableReference<I, M> = MutableReference(immutable, null)
 
     override fun equals(other: Any?): Boolean {