Update SparseArray docs to be more informative.
Change-Id: I5d8d17d46a69ccdcf6b29f93be3d44addd80ab61
diff --git a/core/java/android/util/SparseArray.java b/core/java/android/util/SparseArray.java
index 001fc5b..0e013c3 100644
--- a/core/java/android/util/SparseArray.java
+++ b/core/java/android/util/SparseArray.java
@@ -20,8 +20,25 @@
/**
* SparseArrays map integers to Objects. Unlike a normal array of Objects,
- * there can be gaps in the indices. It is intended to be more efficient
- * than using a HashMap to map Integers to Objects.
+ * there can be gaps in the indices. It is intended to be more memory efficient
+ * than using a HashMap to map Integers to Objects, both because it avoids
+ * auto-boxing keys and its data structure doesn't rely on an extra entry object
+ * for each mapping.
+ *
+ * <p>Note that this container keeps its mappings in an array data structure,
+ * using a binary search to find keys. The implementation is not intended to be appropriate for
+ * data structures
+ * that may contain large numbers of items. It is generally slower than a traditional
+ * HashMap, since lookups require a binary search and adds and removes require inserting
+ * and deleting entries in the array. For containers holding up to hundreds of items,
+ * the performance difference is not significant, less than 50%.</p>
+ *
+ * <p>To help with performance, the container includes an optimization when removing
+ * keys: instead of compacting its array immediately, it leaves the removed entry marked
+ * as deleted. The entry can then be re-used for the same key, or compacted later in
+ * a single garbage collection step of all removed entries. This garbage collection will
+ * need to be performed at any time the array needs to be grown or the the map size or
+ * entry values are retrieved.</p>
*/
public class SparseArray<E> implements Cloneable {
private static final Object DELETED = new Object();