david - writing code documentation...

3 files changed, 306 insertions, 0 deletions

diff --git a/src/fstring.h b/src/fstring.h
index 93a0042..9d88bd4 100644
--- a/src/fstring.h
+++ b/src/fstring.h
@@ -29,6 +29,11 @@ namespace Bu
          * almost no overhead in time or memory since a reference is created and no
          * data is actually copied.  This also means that you never need to put any
          * FBasicString into a ref-counting container class.
+         *
+         *@param chr (typename) Type of character (i.e. char)
+         *@param nMinSize (int) Chunk size (default: 256)
+         *@param chralloc (typename) Memory Allocator for chr
+         *@param chunkalloc (typename) Memory Allocator for chr chunks
          */
         template< typename chr, int nMinSize=256, typename chralloc=std::allocator<chr>, typename chunkalloc=std::allocator<struct FStringChunk<chr> > >
         class FBasicString : public Archival
@@ -113,6 +118,14 @@ namespace Bu
                         clear();
                 }
 
+                /**
+                 *@todo void append( const MyType & sData )
+                 */
+
+                /**
+                 * Append data to your string.
+                 *@param pData (const chr *) The data to append.
+                 */
                 void append( const chr *pData )
                 {
                         long nLen;
@@ -126,6 +139,11 @@ namespace Bu
                         appendChunk( pNew );
                 }
 
+                /**
+                 * Append data to your string.
+                 *@param pData (const chr *) The data to append.
+                 *@param nLen (long) The length of the data to append.
+                 */
                 void append( const chr *pData, long nLen )
                 {
                         if( nLen == 0 )
@@ -138,16 +156,28 @@ namespace Bu
                         appendChunk( pNew );
                 }
 
+                /**
+                 * Append a single chr to your string.
+                 *@param cData (const chr &) The character to append.
+                 */
                 void append( const chr &cData )
                 {
                         append( &cData, 1 );
                 }
 
+                /**
+                 * Prepend another FString to this one.
+                 *@param sData (MyType &) The FString to prepend.
+                 */
                 void prepend( const MyType & sData )
                 {
                         prepend( sData.getStr(), sData.getSize() );
                 }
 
+                /**
+                 * Prepend data to your string.
+                 *@param pData (const chr *) The data to prepend.
+                 */
                 void prepend( const chr *pData )
                 {
                         long nLen;
@@ -159,6 +189,11 @@ namespace Bu
                         prependChunk( pNew );
                 }
 
+                /**
+                 * Prepend data to your string.
+                 *@param pData (const chr *) The data to prepend.
+                 *@param nLen (long) The length of the data to prepend.
+                 */
                 void prepend( const chr *pData, long nLen )
                 {
                         Chunk *pNew = newChunk( nLen );
@@ -168,11 +203,22 @@ namespace Bu
                         prependChunk( pNew );
                 }
 
+                /**
+                 *@todo void prepend( const chr &cData )
+                 */
+
+                /**
+                 * Clear all data from the string.
+                 */
                 void clear()
                 {
                         realClear();
                 }
 
+                /**
+                 * Force the string to resize
+                 *@param nNewSize (long) The new size of the string.
+                 */
                 void resize( long nNewSize )
                 {
                         if( nLength == nNewSize )
@@ -190,11 +236,19 @@ namespace Bu
                         nLength = nNewSize;
                 }
 
+                /**
+                 * Get the current size of the string.
+                 *@returns (long) The current size of the string.
+                 */
                 long getSize() const
                 {
                         return nLength;
                 }
                 
+                /**
+                 * Get a pointer to the string array.
+                 *@returns (chr *) The string data.
+                 */
                 chr *getStr()
                 {
                         if( pFirst == NULL )
@@ -204,6 +258,10 @@ namespace Bu
                         return pFirst->pData;
                 }
                 
+                /**
+                 * Get a const pointer to the string array.
+                 *@returns (const chr *) The string data.
+                 */
                 const chr *getStr() const
                 {
                         if( pFirst == NULL )
@@ -213,6 +271,10 @@ namespace Bu
                         return pFirst->pData;
                 }
 
+                /**
+                 * (std::string compatability) Get a pointer to the string array.
+                 *@returns (chr *) The string data.
+                 */
                 chr *c_str()
                 {
                         if( pFirst == NULL )
@@ -222,6 +284,10 @@ namespace Bu
                         return pFirst->pData;
                 }
                 
+                /**
+                 * (std::string compatability) Get a const pointer to the string array.
+                 *@returns (const chr *) The string data.
+                 */
                 const chr *c_str() const
                 {
                         if( pFirst == NULL )
@@ -231,6 +297,10 @@ namespace Bu
                         return pFirst->pData;
                 }
 
+                /**
+                 * Plus equals operator for FString.
+                 *@param pData (const chr *) The data to append to your FString.
+                 */
                 MyType &operator +=( const chr *pData )
                 {
                         append( pData );
@@ -238,6 +308,10 @@ namespace Bu
                         return (*this);
                 }
                 
+                /**
+                 * Plus equals operator for FString.
+                 *@param pData (const MyType &) The FString to append to your FString.
+                 */
                 MyType &operator +=( const MyType &rSrc )
                 {
                         if( rSrc.nLength == 0 )
@@ -248,6 +322,10 @@ namespace Bu
                         return (*this);
                 }
 
+                /**
+                 * Plus equals operator for FString.
+                 *@param pData (const chr) The character to append to your FString.
+                 */
                 MyType &operator +=( const chr pData )
                 {
                         append( &pData, 1 );
@@ -255,6 +333,11 @@ namespace Bu
                         return (*this);
                 }
 
+                /**
+                 * Assignment operator.
+                 *@param pData (const chr *) The character array to append to your
+                 *              FString.
+                 */
                 MyType &operator =( const chr *pData )
                 {
                         clear();
@@ -263,18 +346,31 @@ namespace Bu
                         return (*this);
                 }
 
+                /**
+                 * Reset your FString to this character array.
+                 *@param pData (const chr *) The character array to set your FString to.
+                 */
                 void set( const chr *pData )
                 {
                         clear();
                         append( pData );
                 }
 
+                /**
+                 * Reset your FString to this character array.
+                 *@param pData (const chr *) The character array to set your FString to.
+                 *@param nSize (long) The length of the inputted character array.
+                 */
                 void set( const chr *pData, long nSize )
                 {
                         clear();
                         append( pData, nSize );
                 }
 
+                /**
+                 * Assignment operator.
+                 *@param rSrc (const MyType &) The FString to set your FString to.
+                 */
                 MyType &operator =( const MyType &rSrc )
                 {
                         //if( rSrc.isFlat() )
@@ -290,6 +386,11 @@ namespace Bu
                         return (*this);
                 }
                 
+                /**
+                 * Equals comparison operator.
+                 *@param pData (const chr *) The character array to compare your FString
+                 *              to.
+                 */
                 bool operator ==( const chr *pData ) const
                 {
                         if( pFirst == NULL ) {
@@ -310,6 +411,10 @@ namespace Bu
                         return true;
                 }
                 
+                /**
+                 * Equals comparison operator.
+                 *@param pData (const MyType &) The FString to compare your FString to.
+                 */
                 bool operator ==( const MyType &pData ) const
                 {
                         if( pFirst == pData.pFirst )
@@ -330,16 +435,30 @@ namespace Bu
                         return true;
                 }
 
+                /**
+                 * Not equals comparison operator.
+                 *@param pData (const chr *) The character array to compare your FString
+                 *              to.
+                 */
                 bool operator !=(const chr *pData ) const
                 {
                         return !(*this == pData);
                 }
                 
+                /**
+                 * Not equals comparison operator.
+                 *@param pData (const MyType &) The FString to compare your FString to.
+                 */
                 bool operator !=(const MyType &pData ) const
                 {
                         return !(*this == pData);
                 }
 
+                /**
+                 * Indexing operator
+                 *@param nIndex (long) The index of the character you want.
+                 *@returns (chr &) The character at position (nIndex).
+                 */
                 chr &operator[]( long nIndex )
                 {
                         flatten();
@@ -347,6 +466,11 @@ namespace Bu
                         return pFirst->pData[nIndex];
                 }
                 
+                /**
+                 * Const indexing operator
+                 *@param nIndex (long) The index of the character you want.
+                 *@returns (const chr &) The character at position (nIndex).
+                 */
                 const chr &operator[]( long nIndex ) const
                 {
                         flatten();
@@ -354,6 +478,11 @@ namespace Bu
                         return pFirst->pData[nIndex];
                 }
 
+                /**
+                 * Is the character at index (nIndex) white space?
+                 *@param nIndex (long) The index of the character you want to check.
+                 *@returns (bool) Is it white space?
+                 */
                 bool isWS( long nIndex ) const
                 {
                         flatten();
@@ -362,6 +491,11 @@ namespace Bu
                                 || pFirst->pData[nIndex]=='\r' || pFirst->pData[nIndex]=='\n';
                 }
 
+                /**
+                 * Is the character at index (nIndex) a letter?
+                 *@param nIndex (long) The index of the character you want to check.
+                 *@returns (bool) Is it a letter?
+                 */
                 bool isAlpha( long nIndex ) const
                 {
                         flatten();
@@ -370,6 +504,9 @@ namespace Bu
                                 || (pFirst->pData[nIndex] >= 'A' && pFirst->pData[nIndex] <= 'Z');
                 }
 
+                /**
+                 * Convert your alpha characters to lower case.
+                 */
                 void toLower()
                 {
                         flatten();
@@ -382,6 +519,9 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Convert your alpha characters to upper case.
+                 */
                 void toUpper()
                 {
                         flatten();
@@ -394,6 +534,11 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Find the index of the first occurrance of (sText)
+                 *@param sText (const char *) The string to search for.
+                 *@returns (long) The index of the first occurrance. -1 for not found.
+                 */
                 long find( const char *sText )
                 {
                         long nTLen = strlen( sText );
@@ -406,6 +551,11 @@ namespace Bu
                         return -1;
                 }
 
+                /**
+                 * Do a reverse search for (sText)
+                 *@param sText (const char *) The string to search for.
+                 *@returns (long) The index of the last occurrance. -1 for not found.
+                 */
                 long rfind( const char *sText )
                 {
                         long nTLen = strlen( sText );
@@ -418,6 +568,10 @@ namespace Bu
                         return -1;
                 }
 
+                /**
+                 * Function the archiver calls to archive your FString.
+                 *@param ar (Archive) The archive which is archiving your FString.
+                 */
                 void archive( class Archive &ar )
                 {
                         if( ar.isLoading() )
diff --git a/src/hash.h b/src/hash.h
index 1bb25c9..6c4a443 100644
--- a/src/hash.h
+++ b/src/hash.h
@@ -71,6 +71,10 @@ namespace Bu
                 bool bFilled;
 
         public:
+                /**
+                 * Cast operator for HashProxy.
+                 *@returns (value_type &) The value the HashProxy is pointing to.
+                 */
                 operator _value &()
                 {
                         if( bFilled == false )
@@ -81,6 +85,10 @@ namespace Bu
                         return *pValue;
                 }
 
+                /**
+                 * Direct function for retrieving a value out of the HashProxy.
+                 *@returns (value_type &) The value pointed to by this HashProxy.
+                 */
                 _value &value()
                 {
                         if( bFilled == false )
@@ -91,11 +99,17 @@ namespace Bu
                         return *pValue;
                 }
 
+                /**
+                 * Whether this HashProxy points to something real or not.
+                 */
                 bool isFilled()
                 {
                         return bFilled;
                 }
 
+                /**
+                 * Erase the data pointed to by this HashProxy.
+                 */
                 void erase()
                 {
                         if( bFilled )
@@ -105,6 +119,10 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Assign data to this point in the hash table.
+                 *@param nval (value_type) the data to assign.
+                 */
                 _value operator=( _value nval )
                 {
                         if( bFilled )
@@ -122,6 +140,11 @@ namespace Bu
                         return nval;
                 }
 
+                /**
+                 * Pointer extraction operator. Access to members of data pointed to
+                 *              by HashProxy.
+                 *@returns (value_type *)
+                 */
                 _value *operator->()
                 {
                         if( bFilled == false )
@@ -133,6 +156,15 @@ namespace Bu
                 }
         };
 
+        /**
+         * Libbu Template Hash Table
+         *@param key (typename) The datatype of the hashtable keys
+         *@param value (typename) The datatype of the hashtable data
+         *@param sizecalc (typename) Functor to compute new table size on rehash
+         *@param keyalloc (typename) Memory allocator for hashtable keys
+         *@param valuealloc (typename) Memory allocator for hashtable values
+         *@param challoc (typename) Byte allocator for bitflags
+         */
         template<typename key, typename value, typename sizecalc, typename keyalloc, typename valuealloc, typename challoc >
         class Hash
         {
@@ -186,6 +218,10 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Hashtable assignment operator. Clears this hashtable and
+                 * copies RH into it.
+                 */
                 Hash &operator=( const Hash &src )
                 {
                         for( uint32_t j = 0; j < nCapacity; j++ )
@@ -244,26 +280,49 @@ namespace Bu
                         ca.deallocate( aHashCodes, nCapacity );
                 }
 
+                /**
+                 * Get the current hash table capacity. (Changes at re-hash)
+                 *@returns (uint32_t) The current capacity.
+                 */
                 uint32_t getCapacity()
                 {
                         return nCapacity;
                 }
 
+                /**
+                 * Get the number of hash locations spoken for. (Including 
+                 * not-yet-cleaned-up deleted items.)
+                 *@returns (uint32_t) The current fill state.
+                 */
                 uint32_t getFill()
                 {
                         return nFilled;
                 }
 
+                /**
+                 * Get the number of items stored in the hash table.
+                 *@returns (uint32_t) The number of items stored in the hash table.
+                 */
                 uint32_t size()
                 {
                         return nFilled-nDeleted;
                 }
 
+                /**
+                 * Get the number of items which have been deleted, but not yet
+                 * cleaned up.
+                 *@returns (uint32_t) The number of deleted items.
+                 */
                 uint32_t getDeleted()
                 {
                         return nDeleted;
                 }
 
+                /**
+                 * Hash table index operator
+                 *@param k (key_type) Key of data to be retrieved.
+                 *@returns (HashProxy) Proxy pointing to the data.
+                 */
                 virtual HashProxy<key, value, sizecalc, keyalloc, valuealloc, challoc> operator[]( key k )
                 {
                         uint32_t hash = __calcHashCode( k );
@@ -280,6 +339,11 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Insert a value (v) under key (k) into the hash table
+                 *@param k (key_type) Key to list the value under.
+                 *@param v (value_type) Value to store in the hash table.
+                 */
                 virtual void insert( key k, value v )
                 {
                         uint32_t hash = __calcHashCode( k );
@@ -299,6 +363,10 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Remove a value from the hash table.
+                 *@param k (key_type) The data under this key will be erased.
+                 */
                 virtual void erase( key k )
                 {
                         uint32_t hash = __calcHashCode( k );
@@ -313,6 +381,11 @@ namespace Bu
                 }
 
                 struct iterator;
+
+                /**
+                 * Remove a value from the hash pointed to from an iterator.
+                 *@param i (iterator &) The data to be erased.
+                 */
                 virtual void erase( struct iterator &i )
                 {
                         if( this != &i.hsh )
@@ -324,6 +397,9 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Remove all data from the hash table.
+                 */
                 virtual void clear()
                 {
                         for( uint32_t j = 0; j < nCapacity; j++ )
@@ -340,6 +416,11 @@ namespace Bu
                         clearBits();
                 }
 
+                /**
+                 * Get an item of data from the hash table.
+                 *@param k (key_type) Key pointing to the data to be retrieved.
+                 *@returns (value_type &) The data pointed to by (k).
+                 */
                 virtual value &get( key k )
                 {
                         uint32_t hash = __calcHashCode( k );
@@ -359,6 +440,12 @@ namespace Bu
                         }
                 }
                 
+                /**
+                 * Get a const item of data from the hash table.
+                 *@param k (key_type) Key pointing to the data to be retrieved.
+                 *@returns (const value_type &) A const version of the data pointed
+                 *              to by (k).
+                 */
                 virtual const value &get( key k ) const
                 {
                         uint32_t hash = __calcHashCode( k );
@@ -378,6 +465,11 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Does the hash table contain an item under key (k).
+                 *@param k (key_type) The key to check.
+                 *@returns (bool) Whether there was an item in the hash under key (k).
+                 */
                 virtual bool has( key k )
                 {
                         bool bFill;
@@ -386,6 +478,9 @@ namespace Bu
                         return bFill;
                 }
 
+                /**
+                 * Iteration structure for iterating through the hash.
+                 */
                 typedef struct iterator
                 {
                         friend class Hash<key, value, sizecalc, keyalloc, valuealloc, challoc>;
@@ -410,6 +505,9 @@ namespace Bu
                         bool bFinished;
 
                 public:
+                        /**
+                         * Iterator incrementation operator. Move the iterator forward.
+                         */
                         iterator operator++( int )
                         {
                                 if( bFinished == false )
@@ -418,6 +516,9 @@ namespace Bu
                                 return *this;
                         }
                         
+                        /**
+                         * Iterator incrementation operator. Move the iterator forward.
+                         */
                         iterator operator++()
                         {
                                 if( bFinished == false )
@@ -426,6 +527,9 @@ namespace Bu
                                 return *this;
                         }
 
+                        /**
+                         * Iterator equality comparison operator. Iterators the same?
+                         */
                         bool operator==( const iterator &oth )
                         {
                                 if( bFinished != oth.bFinished )
@@ -442,11 +546,17 @@ namespace Bu
                                 }
                         }
                         
+                        /**
+                         * Iterator not equality comparison operator. Not the same?
+                         */
                         bool operator!=( const iterator &oth )
                         {
                                 return !(*this == oth );
                         }
 
+                        /**
+                         * Iterator assignment operator.
+                         */
                         iterator operator=( const iterator &oth )
                         {
                                 if( &hsh != &oth.hsh )
@@ -456,32 +566,59 @@ namespace Bu
                                 bFinished = oth.bFinished;
                         }
 
+                        /**
+                         * Iterator dereference operator... err.. get the value
+                         *@returns (value_type &) The value behind this iterator.
+                         */
                         value &operator *()
                         {
                                 return hsh.getValueAtPos( nPos );
                         }
                         
+                        /**
+                         * Get the key behind this iterator.
+                         *@returns (key_type &) The key behind this iterator.
+                         */
                         key &getKey()
                         {
                                 return hsh.getKeyAtPos( nPos );
                         }
 
+                        /**
+                         * Get the value behind this iterator.
+                         *@returs (value_type &) The value behind this iterator.
+                         */
                         value &getValue()
                         {
                                 return hsh.getValueAtPos( nPos );
                         }
                 };
 
+                /**
+                 * Get an iterator pointing to the first item in the hash table.
+                 *@returns (iterator) An iterator pointing to the first item in the
+                 *              hash table.
+                 */
                 iterator begin()
                 {
                         return iterator( *this );
                 }
                 
+                /**
+                 * Get an iterator pointing to a point just past the last item in the
+                 *              hash table.
+                 *@returns (iterator) An iterator pointing to a point just past the
+                 *              last item in the hash table.
+                 */
                 iterator end()
                 {
                         return iterator( *this, true );
                 }
 
+                /**
+                 * Get a list of all the keys in the hash table.
+                 *@returns (std::list<key_type>) The list of keys in the hash table.
+                 */
                 std::list<key> getKeys()
                 {
                         std::list<key> lKeys;
diff --git a/src/list.h b/src/list.h
index 4131987..9d1f904 100644
--- a/src/list.h
+++ b/src/list.h
@@ -21,6 +21,10 @@ namespace Bu
          * members are only accessable const.  Third, erasing a location does not
          * invalidate the iterator, it simply points to the next valid location, or
          * end() if there are no more.
+         *
+         *@param value (typename) The type of data to store in your list
+         *@param valuealloc (typename) Memory Allocator for your value type
+         *@param linkalloc (typename) Memory Allocator for the list links.
          */
         template<typename value, typename valuealloc=std::allocator<value>, typename linkalloc=std::allocator<struct ListLink<value> > >
         class List
@@ -53,6 +57,10 @@ namespace Bu
                         clear();
                 }
 
+                /**
+                 * Assignment operator.
+                 *@param src (const MyType &) The list to assign to your list.
+                 */
                 MyType &operator=( const MyType &src )
                 {
                         clear();
@@ -62,6 +70,9 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Clear the data from the list.
+                 */
                 void clear()
                 {
                         Link *pCur = pFirst;
@@ -79,6 +90,10 @@ namespace Bu
                         nSize = 0;
                 }
 
+                /**
+                 * Append a value to the list.
+                 *@param v (const value_type &) The value to append.
+                 */
                 void append( const value &v )
                 {
                         Link *pNew = la.allocate( 1 );