1 files changed, 20 insertions, 0 deletions

diff --git a/src/unstable/blobbuilder.h b/src/unstable/blobbuilder.h
index 483de43..744212a 100644
--- a/src/unstable/blobbuilder.h
+++ b/src/unstable/blobbuilder.h
@@ -61,6 +61,26 @@ namespace Bu
     };
     /** @endcond */
 
+    /**
+     * This makes creating a Blob piece at a time easy and fast.  You can
+     * append, prepend, or insert with reasonable efficiency. The underlying
+     * data structure is currently a linked list, and the individual links are
+     * actually block allocated memory. If an amount of data is appended that
+     * is less than the minimum page size then the minimum page size is
+     * allocated. Subsequent appends will share that allocated buffer until it
+     * is full, at which point a new buffer will be created.  If an amount
+     * greater than the minimum page size is appended then any extra space in
+     * the last buffer is used, and then the rest is placed in a single buffer.
+     * At most one buffer will be allocated for any given append or prepend
+     * operation.  Due to the nature of insert, up to two buffers could be
+     * allocated.
+     *
+     * Insert operations will take O(N) time to find the location to insert to
+     * in the linked list, at that point the foud chunk will be split into two
+     * and the new data will be added at the new location. This will also
+     * attempt to share the existing buffers, but if there's extra it will
+     * allocate a new buffer for the remaining data.
+     */
     class BlobBuilder : public Bu::SharedCore<BlobBuilder, BlobBuilderCore>
     {
     protected: