1 files changed, 46 insertions, 3 deletions

diff --git a/src/stable/myriad.h b/src/stable/myriad.h
index 6168aa2..5accd1e 100644
--- a/src/stable/myriad.h
+++ b/src/stable/myriad.h
@@ -31,10 +31,20 @@ namespace Bu
         };
     subExceptionDeclEnd();
 
+    /**
+     * Myriad Stream Multiplexer. This is a system that allows you to store
+     * many streams within a single backing stream. This is great for databases,
+     * caching, etc. It's fairly lightweight, and allows all streams to grow
+     * dynamically using a block-allocation scheme.  This is used extensively
+     * by the caching system and MyriadFs as well as other systems within
+     * libbu++.
+     */
     class Myriad
     {
     public:
         typedef int32_t StreamId;
+        typedef Bu::Array<StreamId> StreamIdArray;
+        typedef Bu::List<StreamId> StreamIdList;
         enum Mode : int32_t {
             None        = 0x00,
 
@@ -55,8 +65,9 @@ namespace Bu
 
     public:
         /**
-         * Open existing Myriad stream, or initialize a new one if it doesn't
-         * exist.
+         * Open existing Myriad container, or initialize a new one if the
+         * backing stream is empty. If other data is already in the provided
+         * backing stream an error is thrown.
          *
          * Myriad format V0
          *   0 -   3:  Myriad_MAGIC_CODE (0ad3fa84)
@@ -75,8 +86,32 @@ namespace Bu
                 int32_t iPreallocateBlocks=-1 );
         virtual ~Myriad();
 
+        /**
+         * Creates a new stream open in the specified eMode and, optionally,
+         * preallocates the specificed amount of space. The stream is zero
+         * bytes even if space is preallocated. The open stream is returned,
+         * ready for use. Use this if you don't care what the id is of the
+         * newly created stream.
+         */
         MyriadStream create( Mode eMode, int32_t iPreallocateBytes=-1 );
+
+        /**
+         * Open an existing stream or create a new stream with the specified
+         * id (iStream) with the specified eMode. This respects the normal file
+         * modes, see Bu::Myriad::Mode for details.
+         */
         MyriadStream open( StreamId iStream, Mode eMode );
+
+        /**
+         * Allocate a new stream but do not open it, just ensure it exists and
+         * return the id of the newly allocated stream.
+         */
+        StreamId allocate();
+
+        /**
+         * Erase the stream specified by iStream. This only can work when the
+         * stream is not open at the moment.
+         */
         void erase( StreamId iStream );
         void setSize( StreamId iStream, int32_t iNewSize );
         int32_t getSize( StreamId iStream ) const;
@@ -90,7 +125,15 @@ namespace Bu
         int32_t getTotalUsedBytes() const;
         int32_t getTotalUnusedBytes( int32_t iAssumeBlockSize=-1 ) const;
         Bu::BitString buildBlockUseMap() const;
-        Bu::Array<int32_t> buildBlockMap() const;
+        StreamIdArray buildBlockMap() const;
+        
+        /**
+         * Lists all stream ids that you are allowed to open. Technically there
+         * is always a zero stream, but it is used by Myriad for stream/block
+         * accounting. It works like a normal stream but you should not open
+         * it.
+         */
+        StreamIdList getStreamList() const;
 
         /**
          * Flush all caches to the backing stream, write all structural and