Added doxygen comments for all relevant headers in io.

io/CBufferedInputStream.cpp

@@ -11,10 +11,11 @@
 // CBufferedInputStream
 //
 
-CBufferedInputStream::CBufferedInputStream(CMutex* mutex, IJob* closeCB) :
+CBufferedInputStream::CBufferedInputStream(
+				CMutex* mutex, IJob* adoptedCloseCB) :
 	m_mutex(mutex),
 	m_empty(mutex, true),
-	m_closeCB(closeCB),
+	m_closeCB(adoptedCloseCB),
 	m_closed(false),
 	m_hungup(false)
 {
@@ -27,10 +28,10 @@ CBufferedInputStream::~CBufferedInputStream()
 }
 
 void
-CBufferedInputStream::write(const void* data, UInt32 n)
+CBufferedInputStream::write(const void* buffer, UInt32 n)
 {
 	if (!m_hungup && n > 0) {
-		m_buffer.write(data, n);
+		m_buffer.write(buffer, n);
 		m_empty = (m_buffer.getSize() == 0);
 		m_empty.broadcast();
 	}
@@ -44,7 +45,7 @@ CBufferedInputStream::hangup()
 }
 
 UInt32
-CBufferedInputStream::readNoLock(void* dst, UInt32 n, double timeout)
+CBufferedInputStream::readNoLock(void* buffer, UInt32 n, double timeout)
 {
 	if (m_closed) {
 		throw XIOClosed();
@@ -65,8 +66,8 @@ CBufferedInputStream::readNoLock(void* dst, UInt32 n, double timeout)
 		n = count;
 	}
 	if (n > 0) {
-		if (dst != NULL) {
+		if (buffer != NULL) {
-			memcpy(dst, m_buffer.peek(n), n);
+			memcpy(buffer, m_buffer.peek(n), n);
 		}
 		m_buffer.pop(n);
 	}
@@ -97,16 +98,16 @@ CBufferedInputStream::close()
 	m_hungup = true;
 	m_buffer.pop(m_buffer.getSize());
 	m_empty.broadcast();
-	if (m_closeCB) {
+	if (m_closeCB != NULL) {
 		m_closeCB->run();
 	}
 }
 
 UInt32
-CBufferedInputStream::read(void* dst, UInt32 n, double timeout)
+CBufferedInputStream::read(void* buffer, UInt32 n, double timeout)
 {
 	CLock lock(m_mutex);
-	return readNoLock(dst, n, timeout);
+	return readNoLock(buffer, n, timeout);
 }
 
 UInt32

io/CBufferedInputStream.h

@@ -8,35 +8,66 @@
 class CMutex;
 class IJob;
 
+//! Memory buffer input stream
+/*!
+This class provides an input stream that reads from a memory buffer.
+It also provides a means for the owner to ensure thread safe access.
+Typically, an owner object will make this object visible to clients
+that need access to an IInputStream while using the CBufferedInputStream
+methods to write data to the stream.
+*/
 class CBufferedInputStream : public IInputStream {
 public:
-	CBufferedInputStream(CMutex*, IJob* adoptedCloseCB);
+	/*!
+	The \c mutex must not be NULL and will be used to ensure thread
+	safe access.  If \c adoptedCloseCB is not NULL it will be called
+	when close() is called, allowing the creator to detect the close.
+	*/
+	CBufferedInputStream(CMutex* mutex, IJob* adoptedCloseCB);
 	~CBufferedInputStream();
 
-	// the caller is expected to lock the mutex before calling
+	//! @name manipulators
-	// methods unless otherwise noted.
+	//@{
 
-	// manipulators
+	//! Write data to stream
+	/*!
+	Write \c n bytes from \c buffer to the stream.  The mutex must
+	be locked before calling this.
+	*/
+	void				write(const void* buffer, UInt32 n);
 
-	// write() appends n bytes to the buffer
+	//! Hangup stream
-	void				write(const void*, UInt32 n);
+	/*!
-
+	Causes read() to always return immediately.  If there is no
-	// causes read() to always return immediately.  if there is no
+	more data to read then it returns 0.  Further writes are discarded.
-	// more data then it returns 0.  further writes are discarded.
+	The mutex must be locked before calling this.
+	*/
 	void				hangup();
 
-	// same as read() but caller must lock the mutex
+	//! Read from stream
-	UInt32				readNoLock(void*, UInt32 count, double timeout);
+	/*!
+	This is the same as read() but the mutex must be locked before
+	calling this.
+	*/
+	UInt32				readNoLock(void*, UInt32 n, double timeout);
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// same as getSize() but caller must lock the mutex
+	//! Get remaining size of stream
+	/*!
+	This is the same as getSize() but the mutex must be locked before
+	calling this.
+	*/
 	UInt32				getSizeNoLock() const;
 
+	//@}
+
 	// IInputStream overrides
 	// these all lock the mutex for their duration
 	virtual void		close();
-	virtual UInt32		read(void*, UInt32 count, double timeout);
+	virtual UInt32		read(void*, UInt32 n, double timeout);
 	virtual UInt32		getSize() const;
 
 private:

io/CBufferedOutputStream.cpp

@@ -9,9 +9,10 @@
 // CBufferedOutputStream
 //
 
-CBufferedOutputStream::CBufferedOutputStream(CMutex* mutex, IJob* closeCB) :
+CBufferedOutputStream::CBufferedOutputStream(
+				CMutex* mutex, IJob* adoptedCloseCB) :
 	m_mutex(mutex),
-	m_closeCB(closeCB),
+	m_closeCB(adoptedCloseCB),
 	m_empty(mutex, true),
 	m_closed(false)
 {
@@ -54,20 +55,20 @@ CBufferedOutputStream::close()
 
 	m_closed = true;
 	m_buffer.pop(m_buffer.getSize());
-	if (m_closeCB) {
+	if (m_closeCB != NULL) {
 		m_closeCB->run();
 	}
 }
 
 UInt32
-CBufferedOutputStream::write(const void* data, UInt32 n)
+CBufferedOutputStream::write(const void* buffer, UInt32 n)
 {
 	CLock lock(m_mutex);
 	if (m_closed) {
 		throw XIOClosed();
 	}
 
-	m_buffer.write(data, n);
+	m_buffer.write(buffer, n);
 	return n;
 }
 

io/CBufferedOutputStream.h

@@ -8,30 +8,59 @@
 class CMutex;
 class IJob;
 
+//! Memory buffer output stream
+/*!
+This class provides an output stream that writes to a memory buffer.
+It also provides a means for the owner to ensure thread safe access.
+Typically, an owner object will make this object visible to clients
+that need access to an IOutputStream while using the CBufferedOutputStream
+methods to read the data written to the stream.
+*/
 class CBufferedOutputStream : public IOutputStream {
 public:
-	CBufferedOutputStream(CMutex*, IJob* adoptedCloseCB);
+	/*!
+	The \c mutex must not be NULL and will be used to ensure thread
+	safe access.  If \c adoptedCloseCB is not NULL it will be called
+	when close() is called, allowing the creator to detect the close.
+	*/
+	CBufferedOutputStream(CMutex* mutex, IJob* adoptedCloseCB);
 	~CBufferedOutputStream();
 
-	// the caller is expected to lock the mutex before calling
+	//! @name manipulators
-	// methods unless otherwise noted.
+	//@{
 
-	// manipulators
+	//! Read data without removing from buffer
-
+	/*!
-	// peek() returns a buffer of n bytes (which must be <= getSize()).
+	Returns a buffer of \c n bytes (which must be <= getSize()).  The
-	// pop() discards the next n bytes.
+	caller must not modify the buffer nor delete it.  The mutex must
+	be locked before calling this.
+	*/
 	const void*			peek(UInt32 n);
+
+	//! Discard data
+	/*!
+	Discards the next \c n bytes.  If \c n >= getSize() then the buffer
+	is cleared.  The mutex must be locked before calling this.
+	*/
 	void				pop(UInt32 n);
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// return the number of bytes in the buffer
+	//! Get size of buffer
+	/*!
+	Returns the number of bytes in the buffer.  The mutex must be locked
+	before calling this.
+	*/
 	UInt32				getSize() const;
 
+	//@}
+
 	// IOutputStream overrides
 	// these all lock the mutex for their duration
 	virtual void		close();
-	virtual UInt32		write(const void*, UInt32 count);
+	virtual UInt32		write(const void*, UInt32 n);
 	virtual void		flush();
 
 private:

io/CInputStreamFilter.h

@@ -3,21 +3,31 @@
 
 #include "IInputStream.h"
 
+//! A filtering input stream
+/*!
+This class wraps an input stream.  Subclasses provide indirect access
+to the stream, typically performing some filtering.
+*/
 class CInputStreamFilter : public IInputStream {
 public:
-	CInputStreamFilter(IInputStream*, bool adoptStream = true);
+	/*!
+	Create a wrapper around \c stream.  Iff \c adoptStream is true then
+	this object takes ownership of the stream and will delete it in the
+	d'tor.
+	*/
+	CInputStreamFilter(IInputStream* stream, bool adoptStream = true);
 	~CInputStreamFilter();
 
-	// manipulators
-
-	// accessors
-
 	// IInputStream overrides
 	virtual void		close() = 0;
-	virtual UInt32		read(void*, UInt32 maxCount, double timeout) = 0;
+	virtual UInt32		read(void*, UInt32 n, double timeout) = 0;
 	virtual UInt32		getSize() const = 0;
 
 protected:
+	//! Get the stream
+	/*!
+	Returns the stream passed to the c'tor.
+	*/
 	IInputStream*		getStream() const;
 
 private:

io/COutputStreamFilter.h

@@ -3,21 +3,31 @@
 
 #include "IOutputStream.h"
 
+//! A filtering output stream
+/*!
+This class wraps an output stream.  Subclasses provide indirect access
+to the stream, typically performing some filtering.
+*/
 class COutputStreamFilter : public IOutputStream {
 public:
-	COutputStreamFilter(IOutputStream*, bool adoptStream = true);
+	/*!
+	Create a wrapper around \c stream.  Iff \c adoptStream is true then
+	this object takes ownership of the stream and will delete it in the
+	d'tor.
+	*/
+	COutputStreamFilter(IOutputStream* stream, bool adoptStream = true);
 	~COutputStreamFilter();
 
-	// manipulators
-
-	// accessors
-
 	// IOutputStream overrides
 	virtual void		close() = 0;
 	virtual UInt32		write(const void*, UInt32 count) = 0;
 	virtual void		flush() = 0;
 
 protected:
+	//! Get the stream
+	/*!
+	Returns the stream passed to the c'tor.
+	*/
 	IOutputStream*		getStream() const;
 
 private:

io/CStreamBuffer.h

@@ -5,26 +5,51 @@
 #include "stdlist.h"
 #include "stdvector.h"
 
+//! FIFO of bytes
+/*!
+This class maintains a FIFO (first-in, last-out) buffer of bytes.
+*/
 class CStreamBuffer {
 public:
 	CStreamBuffer();
 	~CStreamBuffer();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// peek() returns a buffer of n bytes (which must be <= getSize()).
+	//! Read data without removing from buffer
-	// pop() discards the next n bytes.
+	/*!
+	Return a pointer to memory with the next \c n bytes in the buffer
+	(which must be <= getSize()).  The caller must not modify the returned
+	memory nor delete it.
+	*/
 	const void*			peek(UInt32 n);
+
+	//! Discard data
+	/*!
+	Discards the next \c n bytes.  If \c n >= getSize() then the buffer
+	is cleared.
+	*/
 	void				pop(UInt32 n);
 
-	// write() appends n bytes to the buffer
+	//! Write data to buffer
-	void				write(const void*, UInt32 n);
+	/*!
+	Appends \c n bytes from \c data to the buffer.
+	*/
+	void				write(const void* data, UInt32 n);
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// return the number of bytes in the buffer
+	//! Get size of buffer
+	/*!
+	Returns the number of bytes in the buffer.
+	*/
 	UInt32				getSize() const;
 
+	//@}
+
 private:
 	static const UInt32	kChunkSize;
 

io/IInputStream.h

@@ -4,28 +4,50 @@
 #include "IInterface.h"
 #include "BasicTypes.h"
 
+//! Input stream interface
+/*!
+Defines the interface for all input streams.
+*/
 class IInputStream : public IInterface {
 public:
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// close the stream
+	//! Close the stream
+	/*!
+	Closes the stream.  Attempting to read() after close() throws
+	XIOClosed and getSize() always returns zero.
+	*/
 	virtual void		close() = 0;
 
-	// read up to maxCount bytes into buffer, return number read.
+	//! Read from stream
-	// blocks if no data is currently available.  if buffer is NULL
+	/*!
-	// then the data is discarded.  returns (UInt32)-1 if there's
+	Read up to \c n bytes into buffer, returning the number read.
-	// no data for timeout seconds;  if timeout < 0 then it blocks
+	Blocks for up to \c timeout seconds if no data is available but does
-	// until data is available.
+	not wait if any data is available, even if less than \c n bytes.
-	// (cancellation point)
+	If \c timeout < 0 then it blocks indefinitely until data is available.  
-	virtual UInt32		read(void* buffer, UInt32 maxCount, double timeout) = 0;
+	If \c buffer is NULL then the data is discarded.  Returns (UInt32)-1 if
+	it times out and 0 if no data is available and the other end of the
+	stream has hungup.
 
-	// accessors
+	(cancellation point)
+	*/
+	virtual UInt32		read(void* buffer, UInt32 n, double timeout) = 0;
 
-	// get a conservative estimate of the available bytes to read
+	//@}
-	// (i.e. a number not greater than the actual number of bytes).
+	//! @name accessors
-	// some streams may not be able to determine this and will always
+	//@{
-	// return zero.
+
+	//! Get remaining size of stream
+	/*!
+	Returns a conservative estimate of the available bytes to read
+	(i.e. a number not greater than the actual number of bytes).
+	Some streams may not be able to determine this and will always
+	return zero.
+	*/
 	virtual UInt32		getSize() const = 0;
+
+	//@}
 };
 
 #endif

io/IOutputStream.h

@@ -4,20 +4,41 @@
 #include "IInterface.h"
 #include "BasicTypes.h"
 
+//! Output stream interface
+/*!
+Defines the interface for all output streams.
+*/
 class IOutputStream : public IInterface {
 public:
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// close the stream
+	//! Close the stream
+	/*!
+	Closes the stream.  Attempting to write() after close() throws
+	XIOClosed.
+	*/
 	virtual void		close() = 0;
 
-	// write count bytes to stream
+	//! Write to stream
-	virtual UInt32		write(const void*, UInt32 count) = 0;
+	/*!
+	Write \c n bytes from \c buffer to the stream.  If this can't
+	complete immeditely it will block.  If cancelled, an indeterminate
+	amount of data may have been written.
 
-	// flush the stream
+	(cancellation point)
+	*/
+	virtual UInt32		write(const void* buffer, UInt32 n) = 0;
+
+	//! Flush the stream
+	/*!
+	Waits until all buffered data has been written to the stream.
+
+	(cancellation point)
+	*/
 	virtual void		flush() = 0;
 
-	// accessors
+	//@}
 };
 
 #endif

io/XIO.h

@@ -3,26 +3,41 @@
 
 #include "XBase.h"
 
+//! Generic I/O exception
 class XIO : public XBase { };
 
+//! Generic I/O exception using \c errno
 class XIOErrno : public XIO, public MXErrno {
 public:
 	XIOErrno();
 	XIOErrno(int);
 };
 
+//! I/O closing exception
+/*!
+Thrown if a stream cannot be closed.
+*/
 class XIOClose: public XIOErrno {
 protected:
 	// XBase overrides
 	virtual CString		getWhat() const throw();
 };
 
+//! I/O already closed exception
+/*!
+Thrown when attempting to close or perform I/O on an already closed.
+stream.
+*/
 class XIOClosed : public XIO {
 protected:
 	// XBase overrides
 	virtual CString		getWhat() const throw();
 };
 
+//! I/O end of stream exception
+/*!
+Thrown when attempting to read beyond the end of a stream.
+*/
 class XIOEndOfStream : public XIO {
 protected:
 	// XBase overrides