@@ -22,21 +22,23 @@
@class OFDataArray;
/**
* \brief A base class for different types of streams.
*
- * WARNING: Even though the OFCopying protocol is implemented, it does
- * not return an independant copy of the stream but instead retains it.
- * This is so that the stream can be used as a key for a dictionary so context
- * can be associated with a stream. Using a stream in more than one thread at
- * the same time is not thread-safe, even if copy was called!
- *
- * IMPORTANT: If you want to subclass this, override _readNBytes:intoBuffer:,
- * _writeNBytes:fromBuffer: and _isAtEndOfStream, but nothing else. Those are
- * not defined in the headers, but do the actual work. OFStream uses those and
- * does all the caching and other stuff. If you override these methods without
- * the _ prefix, you *WILL* break caching and get broken results!
+ * \warning Even though the OFCopying protocol is implemented, it does
+ * not return an independant copy of the stream but instead
+ * retains it. This is so that the stream can be used as a key for a
+ * dictionary so context can be associated with a stream. Using a
+ * stream in more than one thread at the same time is not thread-safe,
+ * even if copy was called!
+ *
+ * \warning If you want to subclass this, override _readNBytes:intoBuffer:,
+ * _writeNBytes:fromBuffer: and _isAtEndOfStream, but nothing else.
+ * Those are not defined in the headers, but do the actual work.
+ * OFStream uses those and does all the caching and other stuff. If
+ * you override these methods without the _ prefix, you *WILL* break
+ * caching and get broken results!
*/
@interface OFStream: OFObject
{
char *cache;
char *writeBuffer;
@@ -78,11 +80,11 @@
*
* Unlike readNBytes:intoBuffer:, this method does not return when less than the
* specified length has been read - instead, it waits until it got exactly the
* specified length.
*
- * WARNING: Only call this when you know that specified amount of data is
+ * \warning Only call this when you know that specified amount of data is
* available! Otherwise you will get an exception!
*
* \param buffer The buffer into which the data is read
* \param length The length of the data that should be read.
* The buffer MUST be EXACTLY this big!
@@ -91,61 +93,61 @@
intoBuffer: (void*)buffer;
/**
* \brief Reads a uint8_t from the stream.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A uint8_t from the stream
*/
- (uint8_t)readInt8;
/**
* \brief Reads a uint16_t from the stream which is encoded in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A uint16_t from the stream in native endianess
*/
- (uint16_t)readBigEndianInt16;
/**
* \brief Reads a uint32_t from the stream which is encoded in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A uint32_t from the stream in the native endianess
*/
- (uint32_t)readBigEndianInt32;
/**
* \brief Reads a uint64_t from the stream which is encoded in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A uint64_t from the stream in the native endianess
*/
- (uint64_t)readBigEndianInt64;
/**
* \brief Reads a float from the stream which is encoded in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A float from the stream in the native endianess
*/
- (float)readBigEndianFloat;
/**
* \brief Reads a double from the stream which is encoded in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A double from the stream in the native endianess
*/
- (double)readBigEndianDouble;
@@ -152,11 +154,11 @@
/**
* \brief Reads the specified number of uint16_ts from the stream which are
* encoded in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nInt16s The number of uint16_ts to read
* \param buffer A buffer of sufficient size to store the specified number of
* uint16_ts
@@ -167,11 +169,11 @@
/**
* \brief Reads the specified number of uint32_ts from the stream which are
* encoded in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nInt32s The number of uint32_ts to read
* \param buffer A buffer of sufficient size to store the specified number of
* uint32_ts
@@ -182,11 +184,11 @@
/**
* \brief Reads the specified number of uint64_ts from the stream which are
* encoded in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nInt64s The number of uint64_ts to read
* \param buffer A buffer of sufficient size to store the specified number of
* uint64_ts
@@ -197,11 +199,11 @@
/**
* \brief Reads the specified number of floats from the stream which are encoded
* in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nFloatss The number of floats to read
* \param buffer A buffer of sufficient size to store the specified number of
* floats
@@ -212,11 +214,11 @@
/**
* \brief Reads the specified number of doubles from the stream which are
* encoded in big endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nDoubles The number of doubles to read
* \param buffer A buffer of sufficient size to store the specified number of
* doubles
@@ -226,51 +228,51 @@
intoBuffer: (double*)buffer;
/**
* \brief Reads a uint16_t from the stream which is encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A uint16_t from the stream in native endianess
*/
- (uint16_t)readLittleEndianInt16;
/**
* \brief Reads a uint32_t from the stream which is encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A uint32_t from the stream in the native endianess
*/
- (uint32_t)readLittleEndianInt32;
/**
* \brief Reads a uint64_t from the stream which is encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A uint64_t from the stream in the native endianess
*/
- (uint64_t)readLittleEndianInt64;
/**
* \brief Reads a float from the stream which is encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A float from the stream in the native endianess
*/
- (float)readLittleEndianFloat;
/**
* \brief Reads a double from the stream which is encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \return A double from the stream in the native endianess
*/
- (double)readLittleEndianDouble;
@@ -277,11 +279,11 @@
/**
* \brief Reads the specified number of uint16_ts from the stream which are
* encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nInt16s The number of uint16_ts to read
* \param buffer A buffer of sufficient size to store the specified number of
* uint16_ts
@@ -292,11 +294,11 @@
/**
* \brief Reads the specified number of uint32_ts from the stream which are
* encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nInt32s The number of uint32_ts to read
* \param buffer A buffer of sufficient size to store the specified number of
* uint32_ts
@@ -307,11 +309,11 @@
/**
* \brief Reads the specified number of uint64_ts from the stream which are
* encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nInt64s The number of uint64_ts to read
* \param buffer A buffer of sufficient size to store the specified number of
* uint64_ts
@@ -322,11 +324,11 @@
/**
* \brief Reads the specified number of floats from the stream which are
* encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nFloats The number of floats to read
* \param buffer A buffer of sufficient size to store the specified number of
* floats
@@ -337,11 +339,11 @@
/**
* \brief Reads the specified number of doubles from the stream which are
* encoded in little endian.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nDoubles The number of doubles to read
* \param buffer A buffer of sufficient size to store the specified number of
* doubles
@@ -352,11 +354,11 @@
/**
* \brief Reads the specified number of items with an item size of 1 from the
* stream and returns them in an OFDataArray.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param nItems The number of items to read
* \return An OFDataArray with at nItems items.
*/
@@ -364,11 +366,11 @@
/**
* \brief Reads the specified number of items with the specified item size from
* the stream and returns them in an OFDataArray.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param itemSize The size of each item
* \param nItems The number of items to read
* \return An OFDataArray with at nItems items.
@@ -390,11 +392,11 @@
* If a \\0 appears in the stream, the string will be truncated at the \\0 and
* the rest of the bytes of the string will be lost. This way, reading from the
* stream will not break because of a \\0 because the specified number of bytes
* is still being read and only the string gets truncated.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param length The length (in bytes) of the string to read from the stream
* \return A string with the specified length
*/
@@ -406,11 +408,11 @@
* If a \\0 appears in the stream, the string will be truncated at the \\0 and
* the rest of the bytes of the string will be lost. This way, reading from the
* stream will not break because of a \\0 because the specified number of bytes
* is still being read and only the string gets truncated.
*
- * WARNING: Only call this when you know that enough data is available!
+ * \warning Only call this when you know that enough data is available!
* Otherwise you will get an exception!
*
* \param encoding The encoding of the string to read from the stream
* \param length The length (in bytes) of the string to read from the stream
* \return A string with the specified length