COMMON: Document that Stream API is meant to imitate ISO C FILE seman…

…tics

common/stream.h

@@ -42,12 +42,18 @@ class Stream {
 	 * Returns true if an I/O failure occurred.
 	 * This flag is never cleared automatically. In order to clear it,
 	 * client code has to call clearErr() explicitly.
+	 *
+	 * @note The semantics of any implementation of this method are
+	 * supposed to match those of ISO C ferror().
 	 */
 	virtual bool err() const { return false; }
 
 	/**
 	 * Reset the I/O error status as returned by err().
 	 * For a ReadStream, also reset the end-of-stream status returned by eos().
+	 *
+	 * @note The semantics of any implementation of this method are
+	 * supposed to match those of ISO C clearerr().
 	 */
 	virtual void clearErr() {}
 };
@@ -61,6 +67,9 @@ class WriteStream : virtual public Stream {
 	 * Write data into the stream. Subclasses must implement this
 	 * method; all other write methods are implemented using it.
 	 *
+	 * @note The semantics of any implementation of this method are
+	 * supposed to match those of ISO C fwrite().
+	 *
 	 * @param dataPtr	pointer to the data to be written
 	 * @param dataSize	number of bytes to be written
 	 * @return the number of bytes which were actually written.
@@ -72,6 +81,9 @@ class WriteStream : virtual public Stream {
 	 * storage medium; unbuffered streams can use the default
 	 * implementation.
 	 *
+	 * @note The semantics of any implementation of this method are
+	 * supposed to match those of ISO C fflush().
+	 *
 	 * @return true on success, false in case of a failure
 	 */
 	virtual bool flush() { return true; }
@@ -155,13 +167,22 @@ class ReadStream : virtual public Stream {
 	 * Returns true if a read failed because the stream end has been reached.
 	 * This flag is cleared by clearErr().
 	 * For a SeekableReadStream, it is also cleared by a successful seek.
+	 *
+	 * @note The semantics of any implementation of this method are
+	 * supposed to match those of ISO C feof(). In particular, in a stream
+	 * with N bytes, reading exactly N bytes from the start should *not*
+	 * set eos; only reading *beyond* the available data should set it.
 	 */
 	virtual bool eos() const = 0;
 
 	/**
 	 * Read data from the stream. Subclasses must implement this
 	 * method; all other read methods are implemented using it.
 	 *
+	 * @note The semantics of any implementation of this method are
+	 * supposed to match those of ISO C fread(), in particular where
+	 * it concerns setting error and end of file/stream flags.
+	 *
 	 * @param dataPtr	pointer to a buffer into which the data is read
 	 * @param dataSize	number of bytes to be read
 	 * @return the number of bytes which were actually read.
@@ -335,6 +356,9 @@ class SeekableReadStream : virtual public ReadStream {
 	 * position indicator, or end-of-file, respectively. A successful call
 	 * to the seek() method clears the end-of-file indicator for the stream.
 	 *
+	 * @note The semantics of any implementation of this method are
+	 * supposed to match those of ISO C fseek().
+	 *
 	 * @param offset	the relative offset in bytes
 	 * @param whence	the seek reference: SEEK_SET, SEEK_CUR, or SEEK_END
 	 * @return true on success, false in case of a failure