Really, just a lot of documenting.

14 files changed, 205 insertions, 85 deletions

diff --git a/src/bitstring.h b/src/bitstring.h
index 35f854f..b5f1ada 100644
--- a/src/bitstring.h
+++ b/src/bitstring.h
@@ -202,57 +202,6 @@ namespace Bu
                  */
                 long toLong( long iStart = 0, long iSize = 32 );
 
-                /**
-                 * Converts the data into a human-readable SString object.  SString is
-                 * used to make transport of the string and management very simple.
-                 * Since BitStrings will generally be longer than your average strip of
-                 * ints a faculty is included and turned on by default that will insert
-                 * spacers into the output text every 8 places.  For debugging work,
-                 * this is definately reccomended.
-                 *@param bAddSpacers Leave set to true in order to have the output
-                 * broken into logical groupings of 8 bits per block.  Set to off to
-                 * have a harder
-                 * to read solid block of bits.
-                 *@returns A SString object containing the produced string.
-                 */
-                //std::string toString( bool bAddSpacers = true );
-
-                // Utility
-                /**
-                 * Converts the given number of bits into the smallest allocatable unit,
-                 * which is bytes in C and on most systems nowadays.  This is the
-                 * minimum number of bytes needed to contain the given number of bits,
-                 * so there is generally some slop if they are not evenly divisible.
-                 *@param iBits The number of bits you wish to use.
-                 *@returns The number of bytes you will need to contain the given number
-                 * of bits.
-                 */
-                //static long bitsToBytes( long iBits );
-
-                /**
-                 * Writes all data in the BitString, including a small header block
-                 * describing the number of bits in the BitString to the file described
-                 * by the given file descriptor.  The data writen is purely sequential
-                 * and probably not too easy to read by other mechanisms, although the
-                 * readFromFile function should always be able to do it.  This function
-                 * does not open nor close the file pointed to by fh.
-                 *@param fh The file descriptor of the file to write the data to.
-                 *@returns true if the operation completed without error, false
-                 * otherwise.
-                 */
-                //bool writeToFile( FILE *fh );
-
-                /**
-                 * Reads data formatted by writeToFile and clears out any data that may
-                 * have been in the BitString.  This function preserves nothing in the
-                 * original BitString that it may be replacing.  This function does not
-                 * open nor close the file pointed to by fh.
-                 *@param fh The file descriptor to try to read the data from.
-                 *@returns true if the operation completed without error, false
-                 * otherwise.
-                 */
-                //bool readFromFile( FILE *fh );
-
                 //operators
                 BitString &operator=( const BitString &xSrc );
                 BitString operator~();
diff --git a/src/crypt.cpp b/src/crypt.cpp
index 9111cda..dbf90ab 100644
--- a/src/crypt.cpp
+++ b/src/crypt.cpp
@@ -1,3 +1,10 @@
+/*
+ * Copyright (C) 2007-2008 Xagasoft, All rights reserved.
+ *
+ * This file is part of the libbu++ library and is released under the
+ * terms of the license contained in the file LICENSE.
+ */
+
 #include "bu/crypt.h"
 #include "bu/md5.h"
 #include "bu/base64.h"
diff --git a/src/crypt.h b/src/crypt.h
index 1ea1b85..a38ff52 100644
--- a/src/crypt.h
+++ b/src/crypt.h
@@ -1,3 +1,10 @@
+/*
+ * Copyright (C) 2007-2008 Xagasoft, All rights reserved.
+ *
+ * This file is part of the libbu++ library and is released under the
+ * terms of the license contained in the file LICENSE.
+ */
+
 #ifndef BU_CRYPT_H
 #define BU_CRYPT_H
 
@@ -5,8 +12,8 @@
 
 namespace Bu
 {
-        FString cryptPass( const FString &sPass, const FString &sSalt );
-        FString cryptPass( const FString &sPass );
+        FString cryptPass( const Bu::FString &sPass, const Bu::FString &sSalt );
+        FString cryptPass( const Bu::FString &sPass );
 };
 
 #endif
diff --git a/src/doxy/formatting.dox b/src/doxy/formatting.dox
new file mode 100644
index 0000000..7b440cb
--- /dev/null
+++ b/src/doxy/formatting.dox
@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2007-2008 Xagasoft, All rights reserved.
+ *
+ * This file is part of the libbu++ library and is released under the
+ * terms of the license contained in the file LICENSE.
+ */
+
+/**
+ *@page howto_formatting Formatting data for streams and the console.
+ *
+ * Libbu++ provides a powerful and flexible interface for writing formatted
+ * data easily to any Stream.  This is implemented as a seperate set of
+ * classes from the basic Stream system in order to simplify both systems and
+ * provide additional flexibility and organization.
+ *
+ *@section secBasics The Basics:  Writing to the console (standard i/o)
+ * Libbu++ provides the global variable Bu::sio already instantiated and ready
+ * to be used to access the standard input and output via the Bu::Formatter
+ * class.  If you are familiar with the STL cout then you're practically done.
+ * A quick example may be best.
+ *@code
+#include <bu/sio.h>
+using namespace Bu;
+
+int main()
+{
+        int i = 47;
+
+        sio << "Hello, world." << sio.nl
+                << "Here is a number: " << i << sio.nl;
+
+        return 0;
+}
+@endcode
+ */
diff --git a/src/doxy/groups.dox b/src/doxy/groups.dox
index 9b54950..285923c 100644
--- a/src/doxy/groups.dox
+++ b/src/doxy/groups.dox
@@ -6,26 +6,26 @@
  */
 
 /**
- *@defgroup Threading
+ *@defgroup Threading Threading
  * Threads are awesome.
  */
 
 /**
- *@defgroup Serving
+ *@defgroup Serving Serving
  * Serving data is pretty cool too.
  */
 
 /**
- *@defgroup Containers
+ *@defgroup Containers Containers
  * Containers for data.
  */
 
 /**
- *@defgroup Taf
+ *@defgroup Taf Taf
  * Taf is the best!
  */
 
 /**
- *@defgroup Streams
+ *@defgroup Streams Streams
  * Streams are for data.
  */
diff --git a/src/doxy/main.dox b/src/doxy/main.dox
index 6030f0c..5e822e1 100644
--- a/src/doxy/main.dox
+++ b/src/doxy/main.dox
@@ -18,6 +18,7 @@
  * comprehensive guides and API reference, but doesn't yet.  For now check out
  * these sections:
  * - @ref howto_streams
+ * - @ref howto_formatting
  * - @ref howto_archives
  * - @ref howto_threading
  * - @ref howto_servers
diff --git a/src/doxy/streams.dox b/src/doxy/streams.dox
index 8217210..9655743 100644
--- a/src/doxy/streams.dox
+++ b/src/doxy/streams.dox
@@ -44,11 +44,10 @@
  * data.
  *
  *@section difference How are libbu++ streams different form stl streams?
- * While not globally true, many stl streams are designed for formatting the
- * data that flows through the stream, that means that when you attempt to
- * write a uint32_t into a standard stream it can be difficult to predict what
- * the result will be, will it be the binary representation or a textual
- * conversion?
+ * The most basic difference is that libbu++ streams are geared more towards a
+ * lower level feel, giving you easy and more direct access to many features,
+ * while seperating all of the formatting code used for console I/O and number
+ * to text conversion, etc, in a seperate place.
  *
  * Libbu++ streams are very direct about how the data is handled.  All end-point
  * streams will always handle the data that you provide or request without any
@@ -59,8 +58,8 @@
  * easy as possible to write general code that was as easy as possible to
  * extend, and as clear as possible.  We have accomplished this by making
  * streams simple, yet flexible, with a clear API and a flexible filter system
- * that something geared towards more general formatting, conversion, and
- * operator-only access can't touch.
+ * that something geared towards more general formatting, conversion can't
+ * touch.
  *
  *@section usage Using streams directly
  * To create a stream depends on the type of stream that you're interested in,
diff --git a/src/fbasicstring.h b/src/fbasicstring.h
index b9e4871..fbfc5ef 100644
--- a/src/fbasicstring.h
+++ b/src/fbasicstring.h
@@ -706,6 +706,7 @@ namespace Bu
                 /**
                  * Append another FString to this one.
                  *@param sData (MyType &) The FString to append.
+                 *@param nStart Start position in sData to start copying from.
                  *@param nLen How much data to append.
                  */
                 void append( const MyType & sData, long nStart, long nLen )
@@ -715,6 +716,11 @@ namespace Bu
                         append( sData.getStr(), nStart, nLen );
                 }
                 
+                /**
+                 * Append data to this FString using the passed in iterator as a base.
+                 * The iterator is const, it is not changed.
+                 *@param s Iterator from any compatible FBasicString to copy data from.
+                 */
                 void append( const const_iterator &s )
                 {
                         if( !s.isValid() )
@@ -731,11 +737,24 @@ namespace Bu
                         }
                 }
 
+                /**
+                 * Append data to this FString using the passed in iterator as a base.
+                 * The iterator is const, it is not changed.
+                 *@param s Iterator from any compatible FBasicString to copy data from.
+                 */
                 void append( const iterator &s ) // I get complainst without this one
                 {
                         append( const_iterator( s ) );
                 }
 
+                /**
+                 * Append data to this FString using the passed in iterator as a base,
+                 * and copy data until the ending iterator is reached.  The character
+                 * at the ending iterator is not copied.
+                 * The iterators are const, they are not changed.
+                 *@param s Iterator from any compatible FBasicString to copy data from.
+                 *@param e Iterator to stop copying at.
+                 */
                 void append( const const_iterator &s, const const_iterator &e )
                 {
                         if( !s.isValid() )
@@ -885,10 +904,6 @@ namespace Bu
                 }
 
                 /**
-                 *@todo void prepend( const chr &cData )
-                 */
-
-                /**
                  * Clear all data from the string.
                  */
                 void clear()
@@ -1079,7 +1094,7 @@ namespace Bu
                 
                 /**
                  * Plus equals operator for FString.
-                 *@param pData (const MyType &) The FString to append to your FString.
+                 *@param rSrc (const MyType &) The FString to append to your FString.
                  */
                 MyType &operator+=( const MyType &rSrc )
                 {
@@ -1093,7 +1108,7 @@ namespace Bu
 
                 /**
                  * Plus equals operator for FString.
-                 *@param pData (const chr) The character to append to your FString.
+                 *@param cData (const chr) The character to append to your FString.
                  */
                 MyType &operator+=( const chr cData )
                 {
@@ -1603,7 +1618,8 @@ namespace Bu
 
                 /**
                  * Find the index of the first occurrance of cChar
-                 *@param sText (const chr *) The string to search for.
+                 *@param cChar The character to search for.
+                 *@param iStart The position in the string to start searching from.
                  *@returns (long) The index of the first occurrance. -1 for not found.
                  */
                 long findIdx( const chr cChar, long iStart=0 ) const
@@ -1619,8 +1635,9 @@ namespace Bu
                 
                 /**
                  * Find the index of the first occurrance of sText
-                 *@param cChar (const chr) The character to search for.
-                 *@returns (long) The index of the first occurrance. -1 for not found.
+                 *@param sText The null-terminated string to search for.
+                 *@param iStart The position in the string to start searching from.
+                 *@returns The index of the first occurrance. -1 for not found.
                  */
                 long findIdx( const chr *sText, long iStart=0 ) const
                 {
diff --git a/src/hash.h b/src/hash.h
index 3868a4e..50a35b8 100644
--- a/src/hash.h
+++ b/src/hash.h
@@ -17,8 +17,8 @@
 #include "bu/exceptionbase.h"
 #include "bu/list.h"
 #include "bu/util.h"
-///#include "archival.h"
-///#include "archive.h"
+//#include "archival.h"
+//#include "archive.h"
 
 #define bitsToBytes( n ) (n/32+(n%32>0 ? 1 : 0))
 
@@ -37,6 +37,14 @@ namespace Bu
         template<typename T>
         bool __cmpHashKeys( const T &a, const T &b );
 
+        /**
+         * Default functor used to compute the size of hash tables.  This version
+         * effectively doubles the size of the table when space is low, ensuring
+         * that you always wind up with an odd number for the table size.  A
+         * better but slower option is to always find the next prime number that's
+         * above double your current table size, but that has the potential to be
+         * slower.
+         */
         struct __calcNextTSize_fast
         {
                 uint32_t operator()( uint32_t nCapacity, uint32_t, uint32_t nDeleted ) const
@@ -677,7 +685,7 @@ namespace Bu
 
                         /**
                          * Get the value behind this iterator.
-                         *@returs (value_type &) The value behind this iterator.
+                         *@returns (value_type &) The value behind this iterator.
                          */
                         value &getValue()
                         {
@@ -804,7 +812,7 @@ namespace Bu
 
                         /**
                          * Get the value behind this iterator.
-                         *@returs (value_type &) The value behind this iterator.
+                         *@returns (value_type &) The value behind this iterator.
                          */
                         const value &getValue() const
                         {
diff --git a/src/ito.h b/src/ito.h
index 9829d28..3539929 100644
--- a/src/ito.h
+++ b/src/ito.h
@@ -94,7 +94,7 @@ namespace Bu
                  * the function that actually makes up the thread, it simply calls the
                  * run member function in an OO-friendly way.  This is what allows us to
                  * use member variables from within the thread itself.
-                 *@param Should always be this.
+                 *@param pThread Should always be this.
                  *@returns This is specified by posix, I'm not sure yet.
                  */
                 static void *threadRunner( void *pThread );
diff --git a/src/list.h b/src/list.h
index c517a9e..934766b 100644
--- a/src/list.h
+++ b/src/list.h
@@ -611,7 +611,7 @@ namespace Bu
 
                 /**
                  * Erase an item from the list if you already know the item.
-                 *@param ob The item to find and erase.
+                 *@param v The item to find and erase.
                  */
                 void erase( const value &v )
                 {
diff --git a/src/set.h b/src/set.h
index a25b0bf..aec5781 100644
--- a/src/set.h
+++ b/src/set.h
@@ -184,9 +184,8 @@ namespace Bu
                 }
 
                 /**
-                 * Insert a value (v) under key (k) into the hash table
+                 * Insert key (k) into the set
                  *@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 )
                 {
diff --git a/src/tests/console.cpp b/src/tests/console.cpp
new file mode 100644
index 0000000..628482b
--- /dev/null
+++ b/src/tests/console.cpp
@@ -0,0 +1,36 @@
+#include <bu/sio.h>
+using namespace Bu;
+
+#include <iostream>
+using namespace std;
+
+typedef struct Counter
+{
+        Counter() : i( 0 )
+        {
+        }
+
+        int get()
+        {
+                i++;
+                return i-1;
+        }
+
+        int i;
+} Counter;
+
+template<typename a>
+void runtest( a &out )
+{
+        Counter c;
+        out << c.get() << ", " << c.get() << ", " << c.get() << ", " << c.get() << ", " << c.get() << "\n";
+}
+
+int main()
+{
+        runtest( cout );
+        runtest( sio );
+
+        return 0;
+}
+
diff --git a/src/util.h b/src/util.h
index efbfb26..ea107ee 100644
--- a/src/util.h
+++ b/src/util.h
@@ -19,6 +19,12 @@
 
 namespace Bu
 {
+        /**
+         * Swap the value of two variables, uses references, so it's pretty safe.
+         * Objects passed in must support a basic assignemnt operator (=);
+         *@param a Variable to recieve the value of parameter b
+         *@param b Variable to recieve the value of parameter a
+         */
         template<typename item>
         void swap( item &a, item &b )
         {
@@ -27,36 +33,78 @@ namespace Bu
                 b = tmp;
         }
 
+        /**
+         * Finds the lesser of the two objects, objects passed in must be
+         * less-than-comparable.
+         *@param a A value to test.
+         *@param b Another value to test.
+         *@returns A reference to the lesser of a or b.
+         */
         template<typename item>
         const item &min( const item &a, const item &b )
         {
                 return a<b?a:b;
         }
         
+        /**
+         * Finds the lesser of the two objects, objects passed in must be
+         * less-than-comparable.
+         *@param a A value to test.
+         *@param b Another value to test.
+         *@returns A reference to the lesser of a or b.
+         */
         template<typename item>
         item &min( item &a, item &b )
         {
                 return a<b?a:b;
         }
         
+        /**
+         * Finds the greater of the two objects, objects passed in must be
+         * less-than-comparable.
+         *@param a A value to test.
+         *@param b Another value to test.
+         *@returns A reference to the greater of a or b.
+         */
         template<typename item>
         const item &max( const item &a, const item &b )
         {
-                return a>b?a:b;
+                return b<a?a:b;
         }
         
+        /**
+         * Finds the greater of the two objects, objects passed in must be
+         * less-than-comparable.
+         *@param a A value to test.
+         *@param b Another value to test.
+         *@returns A reference to the greater of a or b.
+         */
         template<typename item>
         item &max( item &a, item &b )
         {
-                return a>b?a:b;
+                return b<a?a:b;
         }
         
+        /**
+         * Given three objects this finds the one between the other two.
+         *@param a A value to test.
+         *@param b Another value to test.
+         *@param c Yet another value to test.
+         *@returns A reference to the mid-value of a, b, and c.
+         */
         template<typename item>
         const item &mid( const item &a, const item &b, const item &c )
         {
                 return min( max( a, b ), c );
         }
-        
+                
+        /**
+         * Given three objects this finds the one between the other two.
+         *@param a A value to test.
+         *@param b Another value to test.
+         *@param c Yet another value to test.
+         *@returns A reference to the mid-value of a, b, and c.
+         */
         template<typename item>
         item &mid( item &a, item &b, item &c )
         {
@@ -66,6 +114,10 @@ namespace Bu
         //
         //  Basic comparison functors
         //
+        /**
+         * Simple less-than comparison functor.  Objects being used should be
+         * less-than-comparable.
+         */
         template<typename item>
         struct __basicLTCmp
         {
@@ -75,6 +127,10 @@ namespace Bu
                 }
         };
         
+        /**
+         * Simple greater-than comparison functor.  Objects being used should be
+         * greater-than-comparable.
+         */
         template<typename item>
         struct __basicGTCmp
         {
@@ -84,6 +140,9 @@ namespace Bu
                 }
         };
 
+        /**
+         * As __basicLTCmp but dereferences the passed in pointers before comparing.
+         */
         template<typename item>
         struct __basicPtrLTCmp
         {
@@ -93,6 +152,9 @@ namespace Bu
                 }
         };
         
+        /**
+         * As __basicGTCmp but dereferences the passed in pointers before comparing.
+         */
         template<typename item>
         struct __basicPtrGTCmp
         {