1 files changed, 34 insertions, 2 deletions
diff --git a/include/core/SkPtrRecorder.h b/include/core/SkPtrRecorder.h
index ff1e14dcb7..66950601a0 100644
--- a/include/core/SkPtrRecorder.h
+++ b/include/core/SkPtrRecorder.h
@@ -20,13 +20,40 @@
 #include "SkRefCnt.h"
 #include "SkTDArray.h"
 
+/**
+ *  Maintains a set of ptrs, assigning each a unique ID [1...N]. Duplicate ptrs
+ *  return the same ID (since its a set). Subclasses can override inPtr()
+ *  and decPtr(). incPtr() is called each time a unique ptr is added ot the
+ *  set. decPtr() is called on each ptr when the set is destroyed or reset.
+ */
 class SkPtrRecorder : public SkRefCnt {
 public:
+    /**
+     *  Add the specified ptr to the set, returning a unique 32bit ID for it
+     *  [1...N]. Duplicate ptrs will return the same ID.
+     *
+     *  If the ptr is NULL, it is not recorded, and 0 is returned.
+     */
     uint32_t recordPtr(void*);
     
+    /**
+     *  Return the number of (non-null) ptrs in the set.
+     */
     int count() const { return fList.count(); }
+
+    /**
+     *  Copy the ptrs in the set into the specified array (allocated by the
+     *  caller). The ptrs are assgined to the array based on their corresponding
+     *  ID. e.g. array[ptr.ID - 1] = ptr.
+     *
+     *  incPtr() and decPtr() are not called during this operation.
+     */
     void getPtrs(void* array[]) const;
 
+    /**
+     *  Call decPtr() on each ptr in the set, and the reset the size of the set
+     *  to 0.
+     */
     void reset();
 
 protected:
@@ -35,9 +62,14 @@ protected:
 
 private:
     struct Pair {
-        void*       fPtr;
-        uint32_t    fIndex;
+        void*       fPtr;   // never NULL
+        uint32_t    fIndex; // 1...N
     };
+
+    // we store the ptrs in sorted-order (using Cmp) so that we can efficiently
+    // detect duplicates when recordPtr() is called. Hence we need to store the
+    // ptr and its ID/fIndex explicitly, since the ptr's position in the array
+    // is not related to its "index".
     SkTDArray<Pair>  fList;
     
     static int Cmp(const Pair& a, const Pair& b);