From eb63011d3f99e0e4f97ec6f0e2319bd4deee9b4f Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sun, 14 Dec 2008 14:51:42 +0000 Subject: [PATCH] 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 | 2 ++ docs/doxygen/overviews/stream.h | 48 ++++++++++++++++------------- interface/wx/stream.h | 12 ++++++-- 3 files changed, 37 insertions(+), 25 deletions(-) diff --git a/docs/doxygen/groups/class_streams.h b/docs/doxygen/groups/class_streams.h index 8b0945196b..9a737b8967 100644 --- 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. +Related overviews: @ref overview_stream + */ diff --git a/docs/doxygen/overviews/stream.h b/docs/doxygen/overviews/stream.h index 6a52ffd6e9..759c0c903d 100644 --- 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 -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 diff --git a/interface/wx/stream.h b/interface/wx/stream.h index 2524ef9120..0d7511ce44 100644 --- a/interface/wx/stream.h +++ b/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() -- 2.47.2