reformat stream overview and provide a description hopefully correct, even if very short, for wxStreamBuffer

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@57332 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/groups/class_streams.h

@@ -14,5 +14,7 @@
 wxWidgets has its own set of stream classes, as an alternative to often buggy
 standard stream libraries, and to provide enhanced functionality.
 
+Related overviews: @ref overview_stream
+
 */
 

docs/doxygen/overviews/stream.h

@@ -29,43 +29,47 @@ Classes:
 
 Standard C++ streams can cause problems on several platforms: they work quite
 well in most cases, but in the multi-threaded case, for example, they have many
-problems. Some Borland compilers refuse to work at all with them and using
-iostreams on Linux makes writing programs that are binary compatible across
-different Linux distributions, impossible.
+problems. Some Borland compilers refuse to work at all with them.
+@todo is this still true?
 
-Therefore, wxStreams have been added to wxWidgets so that applications can
+Besides, using @c std::iostream on Linux makes impossible to write programs that are
+binary compatible across different Linux distributions.
+
+Therefore, wxStreams have been added to wxWidgets so that an applications can
 reliably compile and run on all supported platforms without dependence on a
 particular release of libg++.
 
-wxStreams is divided in two main parts:
+wxStream classes are divided in two main groups:
 
 @li The core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
-    wxFilterIn/OutputStream
-@li The "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream,
-    wxFileIn/OutputStream, ...
+    wxFilterInputStream, wxFilterOutputStream
+@li The "IO" classes: wxSocketInputStream, wxSocketOutputStream,
+    wxFileInputStream, wxFileOutputStream, ...
 
 wxStreamBase is the base definition of a stream. It defines, for example, the
-API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions are
-really implemented by the "IO" classes. wxInputStream and wxOutputStream
-inherit from it.
+API of OnSysRead(), OnSysWrite(), OnSysSeek() and OnSysTell(). These functions are
+really implemented by the "IO" classes.
+wxInputStream and wxOutputStream classes inherit from wxStreamBase and provide
+specialized methods for input and output.
 
 wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer
-linked to a stream. One stream can have multiple stream buffers  but one stream
-have always one autoinitialized stream buffer.
+linked to a stream. One stream can have multiple stream buffers but one stream
+has always one autoinitialized stream buffer.
 
-wxInputStream is the base class for read-only streams. It implements Read,
-SeekI (I for Input), and all read or IO generic related functions.
-wxOutputStream does the same thing but it is for write-only streams.
+wxInputStream is the base class for read-only streams. It implements Read(),
+SeekI() (I for Input), and all read or IO generic related functions.
+wxOutputStream does the same thing for write-only streams.
 
-wxFilterIn/OutputStream is the base class definition for stream filtering.
+wxFilterInputStream and wxFileterOutputStream are the base class definitions for
+stream filtering.
 Stream filtering means a stream which does no syscall but filters data which
-are passed to it and then pass them to another stream. For example,
-wxZLibInputStream is an inline stream decompressor.
+are passed to it and then pass them to another stream.
+For example, wxZLibInputStream is an inline stream decompressor.
 
 The "IO" classes implements the specific parts of the stream. This could be
-nothing in the case of wxMemoryIn/OutputStream which bases itself on
-wxStreamBuffer. This could also be a simple link to the a true syscall (for
-example read(...), write(...)).
+nothing in the case of wxMemoryInputStream and wxMemoryOutputStream which base
+themselves on wxStreamBuffer.
+This could also be a simple link to the true syscall (for example read(...), write(...)).
 
 
 @section overview_stream_example Example

interface/wx/stream.h

@@ -99,12 +99,16 @@ public:
 /**
     @class wxStreamBuffer
 
-    @todo WRITE A DESCRIPTION
+    wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer
+    linked to a stream.
+
+    Each stream always has one autoinitialized stream buffer, but you may
+    attach more of them to the same stream.
 
     @library{wxbase}
     @category{streams}
 
-    @see wxStreamBase
+    @see wxStreamBase, @ref overview_stream
 */
 class wxStreamBuffer
 {
@@ -127,7 +131,9 @@ public:
 
         @code
         streambuffer.Read(...);
-        streambuffer2.Read(...); // This call erases previous error messages set by 'streambuffer'
+        streambuffer2.Read(...);
+            // This call erases previous error messages set by 'streambuffer'
+            // assuming that both instances are stream buffers for the same stream
         @endcode
 
         @see SetBufferIO()