--- a/src/examples/Buffer/Buffer.hpp	Sat Mar 20 14:45:44 2010 +0100
+++ b/src/examples/Buffer/Buffer.hpp	Sat Mar 20 22:02:22 2010 +0100
@@ -4,24 +4,117 @@
 #include <streambuf>
 #include <vector>
 
-class	Buffer : public std::streambuf
+/**
+ **
+ ** @brief This class is an example of a simple implementation of std::streambuf.
+ ** It's purpose is only to show how streambuf works.
+ ** The full documentation is available here:
+ ** @link a http://cplusplus.com/reference/iostream/streambuf/ @endlink
+ **
+ ** According to the official documentation, we will call @b put, all operations
+ ** that fill the buffer (such operations are performed by std::ostream)
+ ** and we will call @b get, all operations that consume the buffer's content
+ ** (operations performed by std::istream)
+ **
+ ** The std::streambuf abstract class works with two pointers. One @b get pointer
+ ** and one @b put pointer. These pointers are sets by two methods:
+ ** setp (set the put pointer)
+ ** setg (set the get pointer).
+ ** Anyway, these pointers can be moved using seekoff and seekpos.
+ ** Any operation that add or remove content from the buffer should move the
+ ** appropriate pointer.
+ **
+ */
+class	StreamBufferImpl : public std::streambuf
 {
 
 public:
 
-    Buffer(void);
-    virtual ~Buffer(void) { }
+    StreamBufferImpl(void);
+    virtual ~StreamBufferImpl(void) { }
 
 protected:
+    /**
+     ** @brief This method sets a new buffer for the put/get operations
+     ** This method is called by pubsetbuf.
+     ** @param [in] s A pointer to the array of char where operations will be performed
+     ** @param [in] n An integer giving the size of the array
+     ** @return A pointer to the class itself
+     */
+    virtual StreamBufferImpl *  setbuf(char *s, std::streamsize n);
 
-    virtual int		sync(void);
-    virtual int		underflow(void);
+    /**
+     ** @brief This method set the @b get and/or @b put pointer to a relative position.
+     ** @param [in] off offset value.
+     ** @param [in] way Where the offset takes effect. The possible values are
+     **   @li @c std::ios_base::beg from the beginning of the stream buffer
+     **   @li @c std::ios_base::cur from the current position in the stream buffer
+     **   @li @c std::ios_base::end from the end of the stream buffer
+     ** @param [in] which Allow us to choose which pointer should be moved.
+     **   @li @c std::ios_base::in Move the @b get pointer.
+     **   @li @c std::ios_base::out Move the @b put pointer.
+     ** @return The new position. Errors (like an invalid position) should be signaled by a value of -1.
+     */
+    virtual std::streampos      seekoff(std::streamoff off,
+                                        std::ios_base::seekdir way,
+                                        std::ios_base::openmode which = std::ios_base::in | std::ios_base::out);
+
+    /**
+     ** @brief This method set the @b get and/or @b put pointer to an absolute position.
+     ** @param [in] sp The pointer new position.
+     ** @param [in] which Allow us to choose which pointer should be moved.
+     **   @li @c std::ios_base::in Move the @b get pointer.
+     **   @li @c std::ios_base::out Move the @b put pointer.
+     ** @return The new position. Errors (like an invalid position) should be signaled by a value of -1.
+     */
+    virtual std::streampos      seekpos(std::streampos sp,
+                                        std::ios_base::openmode which = std::ios_base::in | std::ios_base::out);
+
+    /**
+     ** @brief This method is called when there is a need to synchronize
+     ** the buffer's content with the ``real'' content it represents
+     ** (a device or anything else).
+     ** This method is called when std::endl is applied on a stream
+     ** @return In case of success, zero is returned.
+     ** Errors are expected to be signaled by any other value, like -1.
+     */
+    virtual int                 sync(void);
+
+    virtual std::streamsize     showmanyc(void);
+    virtual std::streamsize     xsgetn(char * s, streamsize n);
+    virtual int                 underflow(void);
+    virtual int                 uflow(void);
+    virtual int                 pbackfail(int c = EOF);
+
+    /**
+     ** @brief This method add content to the buffer.
+     ** @param [in] s An array of char to add to the buffer.
+     ** @param [in] n The array's length
+     ** @return The number of characters written to the buffer.
+     */
+    virtual streamsize  xsputn(const char * s, streamsize n);
+
+    /**
+     ** @brief This method is called when there is no more
+     ** available space on the buffer. This method could be used to allocate a new buffer.
+     ** @param [in] c the character to be written
+     ** @return Any value different than EOF in case of success.
+     ** If the function fails, it should return an EOF or throw an exception
+     */
+    virtual int         overflow(int c = EOF);
 
 private:
-    Buffer(const Buffer & cpy);
+    /**
+     ** @brief std::streambuf has a private copy constructor
+     ** we do the same
+     */
+    StreamBufferImpl(const StreamBufferImpl & cpy);
 
 private:
 
+    /**
+     ** @brief This is the buffer our class will fill or consume
+     */
     std::vector<char>   _rawBuffer;
 
 };