reformat stream overview and provide a description hopefully correct, even if very...

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

diff --git a/docs/doxygen/groups/class_streams.h b/docs/doxygen/groups/class_streams.h
index 8b0945196b596a4c1b296c3a51d0ee79f086b940..9a737b89675d52b83bbbb4d86f09da0a10784081 100644 (file)
--- a/docs/doxygen/groups/class_streams.h
+++ b/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.
 
 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
+

 */
 
 */
 

diff --git a/docs/doxygen/overviews/stream.h b/docs/doxygen/overviews/stream.h
index 6a52ffd6e964df651a2c858acc7710c60df57edb..759c0c903df2b80f8c55cec34c9895bb147eacf0 100644 (file)
--- a/docs/doxygen/overviews/stream.h
+++ b/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
 
 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++.
 
 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,
 
 @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
 
 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
 
 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
 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
 
 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
 
 
 @section overview_stream_example Example

diff --git a/interface/wx/stream.h b/interface/wx/stream.h
index 2524ef912049daf64ca4407d0e1dad0c2fdd1723..0d7511ce4439cfcfbf951cf53400f5c3c3a925c7 100644 (file)
--- a/interface/wx/stream.h
+++ b/interface/wx/stream.h
@@ -99,12 +99,16 @@ public:
 /**
     @class wxStreamBuffer
 
 /**
     @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}
 
 
     @library{wxbase}
     @category{streams}
 

-    @see wxStreamBase
+    @see wxStreamBase, @ref overview_stream

 */
 class wxStreamBuffer
 {
 */
 class wxStreamBuffer
 {


@@ -127,7 +131,9 @@ public:
 
         @code
         streambuffer.Read(...);
 
         @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()
         @endcode
 
         @see SetBufferIO()