Index: src/OFArray.h ================================================================== --- src/OFArray.h +++ src/OFArray.h @@ -257,19 +257,19 @@ * \param block The block to execute for each object */ - (void)enumerateObjectsUsingBlock: (of_array_enumeration_block_t)block; /** - * \brief Returns a new array, mapping each object using the specified block. + * \brief Creates a new array, mapping each object using the specified block. * * \param block A block which maps an object for each object * \return A new, autoreleased OFArray */ - (OFArray*)mappedArrayUsingBlock: (of_array_map_block_t)block; /** - * \brief Returns a new array, only containing the objects for which the block + * \brief Creates a new array, only containing the objects for which the block * returns YES. * * \param block A block which determines if the object should be in the new * array * \return A new, autoreleased OFArray Index: src/OFDataArray+Hashing.h ================================================================== --- src/OFDataArray+Hashing.h +++ src/OFDataArray+Hashing.h @@ -25,12 +25,11 @@ #ifdef __cplusplus } #endif /** - * The OFDataArray (Hashing) category provides methods to calculate hashes for - * data arrays. + * \brief A category which provides methods to calculate hashes for data arrays. */ @interface OFDataArray (Hashing) /** * \brief Returns the MD5 hash of the data array as an autoreleased OFString. * Index: src/OFDate.h ================================================================== --- src/OFDate.h +++ src/OFDate.h @@ -302,22 +302,22 @@ * \return The microseconds part of the seconds the receiver is after the date */ - (uint32_t)microsecondsOfTimeIntervalSinceDate: (OFDate*)otherDate; /** - * \brief Returns a new date with the specified time interval added. + * \brief Creates a new date with the specified time interval added. * * \param seconds The seconds after the date * \return A new, autoreleased OFDate */ - (OFDate*)dateByAddingTimeInterval: (int64_t)seconds; /** - * \brief Returns a new date with the specified time interval added. + * \brief Creates a new date with the specified time interval added. * * \param seconds The seconds after the date * \param microseconds The microseconds after the date * \return A new, autoreleased OFDate */ - (OFDate*)dateByAddingTimeInterval: (int64_t)seconds withMicroseconds: (uint32_t)microseconds; @end Index: src/OFDictionary.h ================================================================== --- src/OFDictionary.h +++ src/OFDictionary.h @@ -191,20 +191,20 @@ */ - (void)enumerateKeysAndObjectsUsingBlock: (of_dictionary_enumeration_block_t)block; /** - * \brief Returns a new dictionary, mapping each object using the specified + * \brief Creates a new dictionary, mapping each object using the specified * block. * * \param block A block which maps an object for each object * \return A new, autorelease OFDictionary */ - (OFDictionary*)mappedDictionaryUsingBlock: (of_dictionary_map_block_t)block; /** - * \brief Returns a new dictionary, only containing the objects for which the + * \brief Creates a new dictionary, only containing the objects for which the * block returns YES. * * \param block A block which determines if the object should be in the new * dictionary * \return A new, autoreleased OFDictionary Index: src/OFIntrospection.h ================================================================== --- src/OFIntrospection.h +++ src/OFIntrospection.h @@ -71,11 +71,11 @@ @property (readonly, copy) OFArray *classMethods; @property (readonly, copy) OFArray *instanceMethods; #endif /** - * \brief Creates a new, autoreleased introspection for the specified class. + * \brief Creates a new introspection for the specified class. * * \return A new, autoreleased introspection for the specified class */ + introspectionWithClass: (Class)class_; @@ -99,7 +99,7 @@ * * \return The instance methods of the class */ - (OFArray*)instanceMethods; -/* TODO: Ivars, properties */ +/* TODO: ivars, properties */ @end Index: src/OFPlugin.h ================================================================== --- src/OFPlugin.h +++ src/OFPlugin.h @@ -32,12 +32,12 @@ { of_plugin_handle_t handle; } /** - * Loads an OFPlugin from a file. + * \brief Loads an OFPlugin from a file. * * \param path Path to the OFPlugin file. The suffix is appended automatically. * \return The loaded OFPlugin */ + pluginFromFile: (OFString*)path; @end Index: src/OFSOCKS5Socket.h ================================================================== --- src/OFSOCKS5Socket.h +++ src/OFSOCKS5Socket.h @@ -25,12 +25,11 @@ OFString *proxyHost; uint16_t proxyPort; } /** - * \brief Creates a new, autoreleased OFSOCKS5Socket which uses the specified - * SOCKS5 proxy. + * \brief Creates a new OFSOCKS5Socket which uses the specified SOCKS5 proxy. * * \param proxyHost The host of the SOCKS5 proxy * \param proxyPort The port of the SOCKS5 proxy * \return A new, autoreleased OFSOCKS5Socket */ Index: src/OFSeekableStream.h ================================================================== --- src/OFSeekableStream.h +++ src/OFSeekableStream.h @@ -28,27 +28,27 @@ * OFStream. If you override these methods without the _ prefix, you *WILL* * break caching, get broken results and seek to the wrong position! */ @interface OFSeekableStream: OFStream /** - * Seeks to the specified absolute offset. + * \brief Seeks to the specified absolute offset. * * \param offset The offset in bytes */ - (void)seekToOffset: (off_t)offset; /** - * Seeks to the specified offset, relative to the current location. + * \brief Seeks to the specified offset, relative to the current location. * * \param offset The offset relative to the current location * \return The absolute offset */ - (off_t)seekForwardWithOffset: (off_t)offset; /** - * Seeks to the specified offset, relative to the end of the stream. + * \brief Seeks to the specified offset, relative to the end of the stream. * * \param offset The offset relative to the end of the stream * \return The absolute offset */ - (off_t)seekToOffsetRelativeToEnd: (off_t)offset; @end Index: src/OFSet.h ================================================================== --- src/OFSet.h +++ src/OFSet.h @@ -31,34 +31,34 @@ * \brief An abstract class for an unordered set of unique objects. */ @interface OFSet: OFObject /** - * \brief Returns a new, autoreleased set. + * \brief Creates a new set. * * \return A new, autoreleased set */ + set; /** - * \brief Returns a new, autoreleased set with the specified set. + * \brief Creates a new set with the specified set. * * \param set The set to initialize the set with * \return A new, autoreleased set with the specified set */ + setWithSet: (OFSet*)set; /** - * \brief Returns a new, autoreleased set with the specified array. + * \brief Creates a new set with the specified array. * * \param array The array to initialize the set with * \return A new, autoreleased set with the specified array */ + setWithArray: (OFArray*)array; /** - * \brief Returns a new, autoreleased set with the specified objects. + * \brief Creates a new set with the specified objects. * * \param firstObject The first object for the set * \return A new, autoreleased set with the specified objects */ + setWithObjects: (id)firstObject, ...; @@ -121,11 +121,11 @@ * \param block The block to execute for each object in the set */ - (void)enumerateObjectsUsingBlock: (of_set_enumeration_block_t)block; /** - * \brief Returns a new set, only containing the objects for which the block + * \brief Creates a new set, only containing the objects for which the block * returns YES. * * \param block A block which determines if the object should be in the new set * \return A new, autoreleased OFSet */ Index: src/OFStream.h ================================================================== --- src/OFStream.h +++ src/OFStream.h @@ -42,11 +42,11 @@ #ifdef OF_HAVE_PROPERTIES @property (assign, setter=setBlocking:) BOOL isBlocking; #endif /** - * Returns a boolean whether the end of the stream has been reached. + * \brief Returns a boolean whether the end of the stream has been reached. * * \return A boolean whether the end of the stream has been reached */ - (BOOL)isAtEndOfStream; @@ -64,14 +64,16 @@ */ - (size_t)readNBytes: (size_t)size intoBuffer: (void*)buffer; /** - * Reads exactly length bytes from the stream into a buffer. Unlike - * readNBytes:intoBuffer:, this method does not return when less than the - * specified length has been read - instead, it waits until it got exactly length - * bytes. + * \brief Reads exactly the specified length bytes from the stream into a + * buffer. + * + * 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 * available! Otherwise you will get an exception! * * \param buffer The buffer into which the data is read @@ -80,71 +82,72 @@ */ - (void)readExactlyNBytes: (size_t)length intoBuffer: (void*)buffer; /** - * Reads a uint8_t from the stream. + * \brief Reads a uint8_t from the stream. * * 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; /** - * Reads a uint16_t from the stream which is encoded in big endian. + * \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! * Otherwise you will get an exception! * * \return A uint16_t from the stream in native endianess */ - (uint16_t)readBigEndianInt16; /** - * Reads a uint32_t from the stream which is encoded in big endian. + * \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! * Otherwise you will get an exception! * * \return A uint32_t from the stream in the native endianess */ - (uint32_t)readBigEndianInt32; /** - * Reads a uint64_t from the stream which is encoded in big endian. + * \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! * Otherwise you will get an exception! * * \return A uint64_t from the stream in the native endianess */ - (uint64_t)readBigEndianInt64; /** - * Reads a float from the stream which is encoded in big endian. + * \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! * Otherwise you will get an exception! * * \return A float from the stream in the native endianess */ - (float)readBigEndianFloat; /** - * Reads a double from the stream which is encoded in big endian. + * \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! * Otherwise you will get an exception! * * \return A double from the stream in the native endianess */ - (double)readBigEndianDouble; /** - * Reads nInt16s uint16_ts from the stream which are encoded in big endian. + * \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! * Otherwise you will get an exception! * * \param nInt16s The number of uint16_ts to read @@ -154,11 +157,12 @@ */ - (size_t)readNBigEndianInt16s: (size_t)nInt16s intoBuffer: (uint16_t*)buffer; /** - * Reads nInt32s uint32_ts from the stream which are encoded in big endian. + * \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! * Otherwise you will get an exception! * * \param nInt32s The number of uint32_ts to read @@ -168,11 +172,12 @@ */ - (size_t)readNBigEndianInt32s: (size_t)nInt32s intoBuffer: (uint32_t*)buffer; /** - * Reads nInt64s uint64_ts from the stream which are encoded in big endian. + * \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! * Otherwise you will get an exception! * * \param nInt64s The number of uint64_ts to read @@ -182,11 +187,12 @@ */ - (size_t)readNBigEndianInt64s: (size_t)nInt64s intoBuffer: (uint64_t*)buffer; /** - * Reads nFloats floats from the stream which are encoded in big endian. + * \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! * Otherwise you will get an exception! * * \param nFloatss The number of floats to read @@ -196,11 +202,12 @@ */ - (size_t)readNBigEndianFloats: (size_t)nFloats intoBuffer: (float*)buffer; /** - * Reads nDoubles doubles from the stream which are encoded in big endian. + * \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! * Otherwise you will get an exception! * * \param nDoubles The number of doubles to read @@ -210,61 +217,62 @@ */ - (size_t)readNBigEndianDoubles: (size_t)nDoubles intoBuffer: (double*)buffer; /** - * Reads a uint16_t from the stream which is encoded in little endian. + * \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! * Otherwise you will get an exception! * * \return A uint16_t from the stream in native endianess */ - (uint16_t)readLittleEndianInt16; /** - * Reads a uint32_t from the stream which is encoded in little endian. + * \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! * Otherwise you will get an exception! * * \return A uint32_t from the stream in the native endianess */ - (uint32_t)readLittleEndianInt32; /** - * Reads a uint64_t from the stream which is encoded in little endian. + * \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! * Otherwise you will get an exception! * * \return A uint64_t from the stream in the native endianess */ - (uint64_t)readLittleEndianInt64; /** - * Reads a float from the stream which is encoded in little endian. + * \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! * Otherwise you will get an exception! * * \return A float from the stream in the native endianess */ - (float)readLittleEndianFloat; /** - * Reads a double from the stream which is encoded in little endian. + * \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! * Otherwise you will get an exception! * * \return A double from the stream in the native endianess */ - (double)readLittleEndianDouble; /** - * Reads nInt16s uint16_ts from the stream which are encoded in little endian. + * \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! * Otherwise you will get an exception! * * \param nInt16s The number of uint16_ts to read @@ -274,11 +282,12 @@ */ - (size_t)readNLittleEndianInt16s: (size_t)nInt16s intoBuffer: (uint16_t*)buffer; /** - * Reads nInt32s uint32_ts from the stream which are encoded in little endian. + * \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! * Otherwise you will get an exception! * * \param nInt32s The number of uint32_ts to read @@ -288,11 +297,12 @@ */ - (size_t)readNLittleEndianInt32s: (size_t)nInt32s intoBuffer: (uint32_t*)buffer; /** - * Reads nInt64s uint64_ts from the stream which are encoded in little endian. + * \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! * Otherwise you will get an exception! * * \param nInt64s The number of uint64_ts to read @@ -302,11 +312,12 @@ */ - (size_t)readNLittleEndianInt64s: (size_t)nInt64s intoBuffer: (uint64_t*)buffer; /** - * Reads nFloats floats from the stream which are encoded in little endian. + * \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! * Otherwise you will get an exception! * * \param nFloats The number of floats to read @@ -316,11 +327,12 @@ */ - (size_t)readNLittleEndianFloats: (size_t)nFloats intoBuffer: (float*)buffer; /** - * Reads nDoubles doubles from the stream which are encoded in little endian. + * \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! * Otherwise you will get an exception! * * \param nDoubles The number of doubles to read @@ -330,12 +342,12 @@ */ - (size_t)readNLittleEndianDoubles: (size_t)nDoubles intoBuffer: (double*)buffer; /** - * Reads nItems items with an item size of 1 from the stream and returns them - * in an OFDataArray. + * \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! * Otherwise you will get an exception! * * \param nItems The number of items to read @@ -342,12 +354,12 @@ * \return An OFDataArray with at nItems items. */ - (OFDataArray*)readDataArrayWithNItems: (size_t)nItems; /** - * Reads nItems items with the specified item size from the stream and returns - * them in an OFDataArray. + * \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! * Otherwise you will get an exception! * * \param itemSize The size of each item @@ -356,21 +368,24 @@ */ - (OFDataArray*)readDataArrayWithItemSize: (size_t)itemSize andNItems: (size_t)nItems; /** + * \brief Returns an OFDataArray with all the remaining data of the stream. + * * \return An OFDataArray with an item size of 1 with all the data of the * stream until the end of the stream is reached. */ - (OFDataArray*)readDataArrayTillEndOfStream; /** - * Reads a string with the specified length from the stream. 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. + * \brief Reads a string with the specified length from the stream. + * + * 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! * Otherwise you will get an exception! * * \param length The length (in bytes) of the string to read from the stream @@ -377,13 +392,14 @@ * \return A string with the specified length */ - (OFString*)readStringWithLength: (size_t)length; /** - * Reads a string with the specified encoding and length from the stream. 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 + * \brief Reads a string with the specified encoding and length from the stream. + * + * 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! * Otherwise you will get an exception! @@ -394,38 +410,40 @@ */ - (OFString*)readStringWithEncoding: (of_string_encoding_t)encoding length: (size_t)length; /** - * Reads until a newline, \\0 or end of stream occurs. + * \brief Reads until a newline, \\0 or end of stream occurs. * * \return The line that was read, autoreleased, or nil if the end of the * stream has been reached. */ - (OFString*)readLine; /** - * Reads with the specified encoding until a newline, \\0 or end of stream - * occurs. + * \brief Reads with the specified encoding until a newline, \\0 or end of + * stream occurs. * * \param encoding The encoding used by the stream * \return The line that was read, autoreleased, or nil if the end of the * stream has been reached. */ - (OFString*)readLineWithEncoding: (of_string_encoding_t)encoding; /** - * Reads until the specified string or \\0 is found or the end of stream occurs. + * \brief Reads until the specified string or \\0 is found or the end of stream + * occurs. * * \param delimiter The delimiter * \return The line that was read, autoreleased, or nil if the end of the * stream has been reached. */ - (OFString*)readTillDelimiter: (OFString*)delimiter; /** - * Reads until the specified string or \\0 is found or the end of stream occurs. + * \brief Reads until the specified string or \\0 is found or the end of stream + * occurs. * * \param delimiter The delimiter * \param encoding The encoding used by the stream * \return The line that was read, autoreleased, or nil if the end of the * stream has been reached. @@ -432,79 +450,82 @@ */ - (OFString*)readTillDelimiter: (OFString*)delimiter withEncoding: (of_string_encoding_t)encoding; /** + * \brief Returns a boolen whether writes are buffered. + * * \return A boolean whether writes are buffered */ - (BOOL)buffersWrites; /** - * Enables or disables the write buffer. + * \brief Enables or disables the write buffer. * * \param enable Whether the write buffer should be enabled or disabled */ - (void)setBuffersWrites: (BOOL)enable; /** - * Writes everythig in the write buffer to the stream. + * \brief Writes everythig in the write buffer to the stream. */ - (void)flushWriteBuffer; /** - * Writes from a buffer into the stream. + * \brief Writes from a buffer into the stream. * * \param buffer The buffer from which the data is written to the stream * \param length The length of the data that should be written */ - (void)writeNBytes: (size_t)length fromBuffer: (const void*)buffer; /** - * Writes a uint8_t into the stream. + * \brief Writes a uint8_t into the stream. * * \param int8 A uint8_t */ - (void)writeInt8: (uint8_t)int8; /** - * Writes a uint16_t into the stream, encoded in big endian. + * \brief Writes a uint16_t into the stream, encoded in big endian. * * \param int16 A uint16_t */ - (void)writeBigEndianInt16: (uint16_t)int16; /** - * Writes a uint32_t into the stream, encoded in big endian. + * \brief Writes a uint32_t into the stream, encoded in big endian. * * \param int32 A uint32_t */ - (void)writeBigEndianInt32: (uint32_t)int32; /** - * Writes a uint64_t into the stream, encoded in big endian. + * \brief Writes a uint64_t into the stream, encoded in big endian. * * \param int64 A uint64_t */ - (void)writeBigEndianInt64: (uint64_t)int64; /** - * Writes a float into the stream, encoded in big endian. + * \brief Writes a float into the stream, encoded in big endian. * * \param float_ A float */ - (void)writeBigEndianFloat: (float)float_; /** - * Writes a double into the stream, encoded in big endian. + * \brief Writes a double into the stream, encoded in big endian. * * \param double_ A double */ - (void)writeBigEndianDouble: (double)double_; /** - * Writes nInt16s uint16_ts into the stream, encoded in big endian. + * \brief Writes the specified number of uint16_ts into the stream, encoded in + * big endian. * * \param nInt16 The number of uint16_ts to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -511,11 +532,12 @@ */ - (size_t)writeNBigEndianInt16s: (size_t)nInt16s fromBuffer: (const uint16_t*)buffer; /** - * Writes nInt32s uint32_ts into the stream, encoded in big endian. + * \brief Writes the specified number of uint32_ts into the stream, encoded in + * big endian. * * \param nInt32 The number of uint32_ts to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -522,11 +544,12 @@ */ - (size_t)writeNBigEndianInt32s: (size_t)nInt32s fromBuffer: (const uint32_t*)buffer; /** - * Writes nInt64s uint64_ts into the stream, encoded in big endian. + * \brief Writes the specified number of uint64_ts into the stream, encoded in + * big endian. * * \param nInt64 The number of uint64_ts to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -533,11 +556,12 @@ */ - (size_t)writeNBigEndianInt64s: (size_t)nInt64s fromBuffer: (const uint64_t*)buffer; /** - * Writes nFloats floats into the stream, encoded in big endian. + * \brief Writes the specified number of floats into the stream, encoded in big + * endian. * * \param nFloats The number of floats to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -544,11 +568,12 @@ */ - (size_t)writeNBigEndianFloats: (size_t)nFloats fromBuffer: (const float*)buffer; /** - * Writes nDoubles doubles into the stream, encoded in big endian. + * \brief Writes the specified number of doubles into the stream, encoded in + * big endian. * * \param nDoubles The number of doubles to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -555,46 +580,47 @@ */ - (size_t)writeNBigEndianDoubles: (size_t)nDoubles fromBuffer: (const double*)buffer; /** - * Writes a uint16_t into the stream, encoded in little endian. + * \brief Writes a uint16_t into the stream, encoded in little endian. * * \param int16 A uint16_t */ - (void)writeLittleEndianInt16: (uint16_t)int16; /** - * Writes a uint32_t into the stream, encoded in little endian. + * \brief Writes a uint32_t into the stream, encoded in little endian. * * \param int32 A uint32_t */ - (void)writeLittleEndianInt32: (uint32_t)int32; /** - * Writes a uint64_t into the stream, encoded in little endian. + * \brief Writes a uint64_t into the stream, encoded in little endian. * * \param int64 A uint64_t */ - (void)writeLittleEndianInt64: (uint64_t)int64; /** - * Writes a float into the stream, encoded in little endian. + * \brief Writes a float into the stream, encoded in little endian. * * \param float_ A float */ - (void)writeLittleEndianFloat: (float)float_; /** - * Writes a double into the stream, encoded in little endian. + * \brief Writes a double into the stream, encoded in little endian. * * \param double_ A double */ - (void)writeLittleEndianDouble: (double)double_; /** - * Writes nInt16s uint16_ts into the stream, encoded in little endian. + * \brief Writes the specified number of uint16_ts into the stream, encoded in + * little endian. * * \param nInt16 The number of uint16_ts to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -601,11 +627,12 @@ */ - (size_t)writeNLittleEndianInt16s: (size_t)nInt16s fromBuffer: (const uint16_t*)buffer; /** - * Writes nInt32s uint32_ts into the stream, encoded in little endian. + * \brief Writes the specified number of uint32_ts into the stream, encoded in + * little endian. * * \param nInt32 The number of uint32_ts to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -612,11 +639,12 @@ */ - (size_t)writeNLittleEndianInt32s: (size_t)nInt32s fromBuffer: (const uint32_t*)buffer; /** - * Writes nInt64s uint64_ts into the stream, encoded in little endian. + * \brief Writes the specified number of uint64_ts into the stream, encoded in + * little endian. * * \param nInt64 The number of uint64_ts to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -623,11 +651,12 @@ */ - (size_t)writeNLittleEndianInt64s: (size_t)nInt64s fromBuffer: (const uint64_t*)buffer; /** - * Writes nFloats floats into the stream, encoded in little endian. + * \brief Writes the specified number of floats into the stream, encoded in + * little endian. * * \param nFloats The number of floats to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -634,11 +663,12 @@ */ - (size_t)writeNLittleEndianFloats: (size_t)nFloats fromBuffer: (const float*)buffer; /** - * Writes nDoubles doubles into the stream, encoded in little endian. + * \brief Writes the specified number of doubles into the stream, encoded in + * little endian. * * \param nDoubles The number of doubles to write * \param buffer The buffer from which the data is written to the stream after * it has been byte swapped if necessary * \return The number of bytes written to the stream @@ -645,35 +675,35 @@ */ - (size_t)writeNLittleEndianDoubles: (size_t)nDoubles fromBuffer: (const double*)buffer; /** - * Writes from an OFDataArray into the stream. + * \brief Writes from an OFDataArray into the stream. * * \param dataArray The OFDataArray to write into the stream * \return The number of bytes written */ - (size_t)writeDataArray: (OFDataArray*)dataArray; /** - * Writes a string into the stream, without the trailing zero. + * \brief Writes a string into the stream, without the trailing zero. * * \param string The string from which the data is written to the stream * \return The number of bytes written */ - (size_t)writeString: (OFString*)string; /** - * Writes a string into the stream with a trailing newline. + * \brief Writes a string into the stream with a trailing newline. * * \param string The string from which the data is written to the stream * \return The number of bytes written */ - (size_t)writeLine: (OFString*)string; /** - * Writes a formatted string into the stream. + * \brief Writes a formatted string into the stream. * * See printf for the format syntax. As an addition, %@ is available as format * specifier for objects. * * \param format A string used as format @@ -680,11 +710,11 @@ * \return The number of bytes written */ - (size_t)writeFormat: (OFConstantString*)format, ...; /** - * Writes a formatted string into the stream. + * \brief Writes a formatted string into the stream. * * See printf for the format syntax. As an addition, %@ is available as format * specifier for objects. * * \param format A string used as format @@ -693,34 +723,40 @@ */ - (size_t)writeFormat: (OFConstantString*)format withArguments: (va_list)arguments; /** + * \brief Returns the number of bytes still present in the internal cache. + * * \return The number of bytes still present in the internal cache. */ - (size_t)pendingBytes; /** + * \brief Returns whether the stream is in blocking mode. + * * \return Whether the stream is in blocking mode */ - (BOOL)isBlocking; /** - * Enables or disables non-blocking I/O. + * \brief Enables or disables non-blocking I/O. * * By default, a stream is in blocking mode. * On Win32, this currently only works for sockets! * * \param enable Whether the stream should be blocking */ - (void)setBlocking: (BOOL)enable; /** - * \return The file descriptor for the stream. + * \brief Returns the file descriptor for the stream. + * + * \return The file descriptor for the stream */ - (int)fileDescriptor; /** - * Closes the stream. + * \brief Closes the stream. */ - (void)close; @end Index: src/OFStreamObserver.h ================================================================== --- src/OFStreamObserver.h +++ src/OFStreamObserver.h @@ -39,25 +39,25 @@ #endif #ifdef OF_HAVE_OPTIONAL_PROTOCOLS @optional #endif /** - * This callback is called when a stream did get ready for reading. + * \brief This callback is called when a stream did get ready for reading. * * \param stream The stream which did become ready for reading */ - (void)streamDidBecomeReadyForReading: (OFStream*)stream; /** - * This callback is called when a stream did get ready for writing. + * \brief This callback is called when a stream did get ready for writing. * * \param stream The stream which did become ready for writing */ - (void)streamDidBecomeReadyForWriting: (OFStream*)stream; /** - * This callback is called when an exception occurred on the stream. + * \brief This callback is called when an exception occurred on the stream. * * \param stream The stream on which an exception occurred */ - (void)streamDidReceiveException: (OFStream*)stream; @end @@ -82,28 +82,32 @@ #ifdef OF_HAVE_PROPERTIES @property (retain) id delegate; #endif /** + * \brief Creates a new OFStreamObserver. + * * \return A new, autoreleased OFStreamObserver */ + observer; /** + * \brief Returns the delegate for the OFStreamObserver. + * * \return The delegate for the OFStreamObserver */ - (id )delegate; /** - * Sets the delegate for the OFStreamObserver. + * \brief Sets the delegate for the OFStreamObserver. * * \param delegate The delegate for the OFStreamObserver */ - (void)setDelegate: (id )delegate; /** - * Adds a stream to observe for reading. + * \brief Adds a stream to observe for reading. * * This is also used to observe a listening socket for incoming connections, * which then triggers a read event for the observed stream. * * It is recommended that the stream you add is set to non-blocking mode. @@ -114,11 +118,11 @@ * \param stream The stream to observe for reading */ - (void)addStreamToObserveForReading: (OFStream*)stream; /** - * Adds a stream to observe for writing. + * \brief Adds a stream to observe for writing. * * It is recommended that the stream you add is set to non-blocking mode. * * If there is an -[observe] call blocking, it will be canceled. The reason for * this is to prevent blocking even though the new added stream is ready. @@ -126,37 +130,37 @@ * \param stream The stream to observe for writing */ - (void)addStreamToObserveForWriting: (OFStream*)stream; /** - * Removes a stream to observe for reading. + * \brief Removes a stream to observe for reading. * * If there is an -[observe] call blocking, it will be canceled. The reason for * this is to prevent the removed stream from still being observed. * * \param stream The stream to remove from observing for reading */ - (void)removeStreamToObserveForReading: (OFStream*)stream; /** - * Removes a stream to observe for writing. + * \brief Removes a stream to observe for writing. * * If there is an -[observe] call blocking, it will be canceled. The reason for * this is to prevent the removed stream from still being observed. * * \param stream The stream to remove from observing for writing */ - (void)removeStreamToObserveForWriting: (OFStream*)stream; /** - * Observes all streams and blocks until an event happens on a stream. + * \brief Observes all streams and blocks until an event happens on a stream. */ - (void)observe; /** - * Observes all streams until an event happens on a stream or the timeout is - * reached. + * \brief Observes all streams until an event happens on a stream or the + * timeout is reached. * * \param timeout The time to wait for an event, in milliseconds * \return A boolean whether events occurred during the timeinterval */ - (BOOL)observeWithTimeout: (int)timeout; Index: src/OFStreamSocket.h ================================================================== --- src/OFStreamSocket.h +++ src/OFStreamSocket.h @@ -31,9 +31,11 @@ int sock; BOOL isAtEndOfStream; } /** - * \return A new autoreleased OFTCPSocket + * \brief Returns a new, autoreleased OFTCPSocket. + * + * \return A new, autoreleased OFTCPSocket */ + socket; @end Index: src/OFString+Hashing.h ================================================================== --- src/OFString+Hashing.h +++ src/OFString+Hashing.h @@ -23,19 +23,23 @@ #ifdef __cplusplus } #endif /** - * The OFString (Hashing) category provides methods to calculate hashes for - * strings. + * \brief The OFString (Hashing) category provides methods to calculate hashes + * for strings. */ @interface OFString (Hashing) /** + * \brief Returns the MD5 hash of the string as an autoreleased OFString. + * * \return The MD5 hash of the string as an autoreleased OFString */ - (OFString*)MD5Hash; /** + * \brief Returns the SHA1 hash of the string as an autoreleased OFString. + * * \return The SHA1 hash of the string as an autoreleased OFString */ - (OFString*)SHA1Hash; @end Index: src/OFString+URLEncoding.h ================================================================== --- src/OFString+URLEncoding.h +++ src/OFString+URLEncoding.h @@ -27,18 +27,18 @@ /** * \brief A category which provides URL encoding and decoding. */ @interface OFString (URLEncoding) /** - * Encodes a string for use in a URL. + * \brief Encodes a string for use in a URL. * * \return A new autoreleased string */ - (OFString*)stringByURLEncoding; /** - * Decodes a string used in a URL. + * \brief Decodes a string used in a URL. * * \return A new autoreleased string */ - (OFString*)stringByURLDecoding; @end Index: src/OFString+XMLEscaping.h ================================================================== --- src/OFString+XMLEscaping.h +++ src/OFString+XMLEscaping.h @@ -27,11 +27,11 @@ /** * \brief A category to escape strings for use in an XML document. */ @interface OFString (XMLEscaping) /** - * Escapes a string for use in an XML document. + * \brief Escapes a string for use in an XML document. * * \return A new autoreleased string */ - (OFString*)stringByXMLEscaping; @end Index: src/OFString+XMLUnescaping.h ================================================================== --- src/OFString+XMLUnescaping.h +++ src/OFString+XMLUnescaping.h @@ -33,14 +33,16 @@ * \brief A protocol that needs to be implemented by delegates for * -[stringByXMLUnescapingWithHandler:]. */ @protocol OFStringXMLUnescapingDelegate /** - * This callback is called when an unknown entity was found while trying to - * unescape XML. The callback is supposed to return a substitution for the - * entity or nil if it is unknown to the callback as well, in which case an - * exception will be thrown. + * \brief This callback is called when an unknown entity was found while trying + * to unescape XML. + * + * The callback is supposed to return a substitution for the entity or nil if + * it is unknown to the callback as well, in which case an exception will be + * thrown. * * \param str The string which contains the unknown entity * \param entity The name of the entity that is unknown * \return A substitution for the entity or nil */ @@ -51,29 +53,29 @@ /** * \brief A category for unescaping XML in strings. */ @interface OFString (XMLUnescaping) /** - * Unescapes XML in the string. + * \brief Unescapes XML in the string. */ - (OFString*)stringByXMLUnescaping; /** - * Unescapes XML in the string and uses the specified delegate for unknown - * entities. + * \brief Unescapes XML in the string and uses the specified delegate for + * unknown entities. * * \param delegate An OFXMLUnescapingDelegate as a handler for unknown entities */ - (OFString*)stringByXMLUnescapingWithDelegate: (id )delegate; #ifdef OF_HAVE_BLOCKS /** - * Unescapes XML in the string and uses the specified block for unknown - * entities. + * \brief Unescapes XML in the string and uses the specified block for unknown + * entities. * * \param block A block which handles unknown entities */ - (OFString*)stringByXMLUnescapingWithBlock: (of_string_xml_unescaping_block_t)block; #endif @end Index: src/OFString.h ================================================================== --- src/OFString.h +++ src/OFString.h @@ -94,35 +94,37 @@ @property (readonly) size_t cStringLength; @property (readonly) size_t length; #endif /** - * \return A new autoreleased OFString + * \brief Creates a new OFString. + * + * \return A new, autoreleased OFString */ + string; /** - * Creates a new OFString from a UTF-8 encoded C string. + * \brief Creates a new OFString from a UTF-8 encoded C string. * * \param cString A UTF-8 encoded C string to initialize the OFString with * \return A new autoreleased OFString */ + stringWithCString: (const char*)cString; /** - * Creates a new OFString from a C string with the specified encoding. + * \brief Creates a new OFString from a C string with the specified encoding. * * \param string A C string to initialize the OFString with * \param encoding The encoding of the C string * \return A new autoreleased OFString */ + stringWithCString: (const char*)cString encoding: (of_string_encoding_t)encoding; /** - * Creates a new OFString from a C string with the specified encoding and - * length. + * \brief Creates a new OFString from a C string with the specified encoding + * and length. * * \param cString A C string to initialize the OFString with * \param encoding The encoding of the C string * \param cStringLength The length of the C string * \return A new autoreleased OFString @@ -130,60 +132,61 @@ + stringWithCString: (const char*)cString encoding: (of_string_encoding_t)encoding length: (size_t)cStringLength; /** - * Creates a new OFString from a UTF-8 encoded C string with the specified - * length. + * \brief Creates a new OFString from a UTF-8 encoded C string with the + * specified length. * * \param cString A UTF-8 encoded C string to initialize the OFString with * \param cStringLength The length of the UTF-8 encoded C string * \return A new autoreleased OFString */ + stringWithCString: (const char*)cString length: (size_t)cStringLength; /** - * Creates a new OFString from another string. + * \brief Creates a new OFString from another string. * * \param string A string to initialize the OFString with * \return A new autoreleased OFString */ + stringWithString: (OFString*)string; /** - * Creates a new OFString from a unicode string. + * \brief Creates a new OFString from a unicode string. * * \param string The unicode string * \return A new autoreleased OFString */ + stringWithUnicodeString: (of_unichar_t*)string; /** - * Creates a new OFString from a unicode string, assuming the specified byte - * order if no BOM is found. + * \brief Creates a new OFString from a unicode string, assuming the specified + * byte order if no BOM is found. * * \param string The unicode string * \param byteOrder The byte order to assume if there is no BOM * \return A new autoreleased OFString */ + stringWithUnicodeString: (of_unichar_t*)string byteOrder: (of_endianess_t)byteOrder; /** - * Creates a new OFString from a unicode string with the specified length. + * \brief Creates a new OFString from a unicode string with the specified + * length. * * \param string The unicode string * \param length The length of the unicode string * \return A new autoreleased OFString */ + stringWithUnicodeString: (of_unichar_t*)string length: (size_t)length; /** - * Creates a new OFString from a unicode string with the specified length, - * assuming the specified byte order if no BOM is found. + * \brief Creates a new OFString from a unicode string with the specified + * length, assuming the specified byte order if no BOM is found. * * \param string The unicode string * \param byteOrder The byte order to assume if there is no BOM * \param length The length of the unicode string * \return A new autoreleased OFString @@ -191,42 +194,43 @@ + stringWithUnicodeString: (of_unichar_t*)string byteOrder: (of_endianess_t)byteOrder length: (size_t)length; /** - * Creates a new OFString from a UTF-16 encoded string. + * \brief Creates a new OFString from a UTF-16 encoded string. * * \param string The UTF-16 string * \return A new autoreleased OFString */ + stringWithUTF16String: (uint16_t*)string; /** - * Creates a new OFString from a UTF-16 encoded string, assuming the specified - * byte order if no BOM is found. + * \brief Creates a new OFString from a UTF-16 encoded string, assuming the + * specified byte order if no BOM is found. * * \param string The UTF-16 string * \param byteOrder The byte order to assume if there is no BOM * \return A new autoreleased OFString */ + stringWithUTF16String: (uint16_t*)string byteOrder: (of_endianess_t)byteOrder; /** - * Creates a new OFString from a UTF-16 encoded string with the specified - * length. + * \brief Creates a new OFString from a UTF-16 encoded string with the specified + * length. * * \param string The UTF-16 string * \param length The length of the unicode string * \return A new autoreleased OFString */ + stringWithUTF16String: (uint16_t*)string length: (size_t)length; /** - * Creates a new OFString from a UTF-16 encoded string with the specified - * length, assuming the specified byte order if no BOM is found. + * \brief Creates a new OFString from a UTF-16 encoded string with the + * specified length, assuming the specified byte order if no BOM is + * found. * * \param string The UTF-16 string * \param byteOrder The byte order to assume if there is no BOM * \param length The length of the unicode string * \return A new autoreleased OFString @@ -234,11 +238,11 @@ + stringWithUTF16String: (uint16_t*)string byteOrder: (of_endianess_t)byteOrder length: (size_t)length; /** - * Creates a new OFString from a format string. + * \brief Creates a new OFString from a format string. * * See printf for the format syntax. As an addition, %@ is available as format * specifier for objects. * * \param format A string used as format to initialize the OFString @@ -245,38 +249,39 @@ * \return A new autoreleased OFString */ + stringWithFormat: (OFConstantString*)format, ...; /** - * Creates a new OFString containing the constructed specified path. + * \brief Creates a new OFString containing the constructed specified path. * * \param firstComponent The first component of the path * \return A new autoreleased OFString */ + stringWithPath: (OFString*)firstComponent, ...; /** - * Creates a new OFString with the contents of the specified UTF-8 encoded file. + * \brief Creates a new OFString with the contents of the specified UTF-8 + * encoded file. * * \param path The path to the file * \return A new autoreleased OFString */ + stringWithContentsOfFile: (OFString*)path; /** - * Creates a new OFString with the contents of the specified file in the - * specified encoding. + * \brief Creates a new OFString with the contents of the specified file in the + * specified encoding. * * \param path The path to the file * \param encoding The encoding of the file * \return A new autoreleased OFString */ + stringWithContentsOfFile: (OFString*)path encoding: (of_string_encoding_t)encoding; /** - * Creates a new OFString with the contents of the specified URL. + * \brief Creates a new OFString with the contents of the specified URL. * * If the URL's scheme is file, it tries UTF-8 encoding. * * If the URL's scheme is http(s), it tries to detect the encoding from the HTTP * headers. If it could not detect the encoding using the HTTP headers, it tries @@ -286,42 +291,43 @@ * \return A new autoreleased OFString */ + stringWithContentsOfURL: (OFURL*)URL; /** - * Creates a new OFString with the contents of the specified URL in the - * specified encoding. + * \brief Creates a new OFString with the contents of the specified URL in the + * specified encoding. * * \param URL The URL to the contents for the string * \param encoding The encoding to assume * \return A new autoreleased OFString */ + stringWithContentsOfURL: (OFURL*)URL encoding: (of_string_encoding_t)encoding; /** - * Initializes an already allocated OFString from a UTF-8 encoded C string. + * \brief Initializes an already allocated OFString from a UTF-8 encoded C + * string. * * \param cString A UTF-8 encoded C string to initialize the OFString with * \return An initialized OFString */ - initWithCString: (const char*)cString; /** - * Initializes an already allocated OFString from a C string with the specified - * encoding. + * \brief Initializes an already allocated OFString from a C string with the + * specified encoding. * * \param cString A C string to initialize the OFString with * \param encoding The encoding of the C string * \return An initialized OFString */ - initWithCString: (const char*)cString encoding: (of_string_encoding_t)encoding; /** - * Initializes an already allocated OFString from a C string with the specified - * encoding and length. + * \brief Initializes an already allocated OFString from a C string with the + * specified encoding and length. * * \param cString A C string to initialize the OFString with * \param encoding The encoding of the C string * \param cStringLength The length of the C string * \return An initialized OFString @@ -329,61 +335,62 @@ - initWithCString: (const char*)cString encoding: (of_string_encoding_t)encoding length: (size_t)cStringLength; /** - * Initializes an already allocated OFString from a UTF-8 encoded C string with - * the specified length. + * \brief Initializes an already allocated OFString from a UTF-8 encoded C + * string with the specified length. * * \param cString A UTF-8 encoded C string to initialize the OFString with * \param cStringLength The length of the UTF-8 encoded C string * \return An initialized OFString */ - initWithCString: (const char*)cString length: (size_t)cStringLength; /** - * Initializes an already allocated OFString with another string. + * \brief Initializes an already allocated OFString with another string. * * \param string A string to initialize the OFString with * \return An initialized OFString */ - initWithString: (OFString*)string; /** - * Initializes an already allocated OFString with a unicode string. + * \brief Initializes an already allocated OFString with a unicode string. * * \param string The unicode string * \return An initialized OFString */ - initWithUnicodeString: (of_unichar_t*)string; /** - * Initializes an already allocated OFString with a unicode string, assuming the - * specified byte order if no BOM is found. + * \brief Initializes an already allocated OFString with a unicode string, + * assuming the specified byte order if no BOM is found. * * \param string The unicode string * \param byteOrder The byte order to assume if there is no BOM * \return An initialized OFString */ - initWithUnicodeString: (of_unichar_t*)string byteOrder: (of_endianess_t)byteOrder; /** - * Initializes an already allocated OFString with a unicode string with the - * specified length. + * \brief Initializes an already allocated OFString with a unicode string with + * the specified length. * * \param string The unicode string * \param length The length of the unicode string * \return An initialized OFString */ - initWithUnicodeString: (of_unichar_t*)string length: (size_t)length; /** - * Initializes an already allocated OFString with a unicode string with the - * specified length, assuming the specified byte order if no BOM is found. + * \brief Initializes an already allocated OFString with a unicode string with + * the specified length, assuming the specified byte order if no BOM is + * found. * * \param string The unicode string * \param byteOrder The byte order to assume if there is no BOM * \param length The length of the unicode string * \return An initialized OFString @@ -391,42 +398,43 @@ - initWithUnicodeString: (of_unichar_t*)string byteOrder: (of_endianess_t)byteOrder length: (size_t)length; /** - * Initializes an already allocated OFString with a UTF-16 string. + * \brief Initializes an already allocated OFString with a UTF-16 string. * * \param string The UTF-16 string * \return An initialized OFString */ - initWithUTF16String: (uint16_t*)string; /** - * Initializes an already allocated OFString with a UTF-16 string, assuming the - * specified byte order if no BOM is found. + * \brief Initializes an already allocated OFString with a UTF-16 string, + * assuming the specified byte order if no BOM is found. * * \param string The UTF-16 string * \param byteOrder The byte order to assume if there is no BOM * \return An initialized OFString */ - initWithUTF16String: (uint16_t*)string byteOrder: (of_endianess_t)byteOrder; /** - * Initializes an already allocated OFString with a UTF-16 string with the - * specified length. + * \brief Initializes an already allocated OFString with a UTF-16 string with + * the specified length. * * \param string The UTF-16 string * \param length The length of the UTF-16 string * \return An initialized OFString */ - initWithUTF16String: (uint16_t*)string length: (size_t)length; /** - * Initializes an already allocated OFString with a UTF-16 string with the - * specified length, assuming the specified byte order if no BOM is found. + * \brief Initializes an already allocated OFString with a UTF-16 string with + * the specified length, assuming the specified byte order if no BOM is + * found. * * \param string The UTF-16 string * \param byteOrder The byte order to assume if there is no BOM * \param length The length of the UTF-16 string * \return An initialized OFString @@ -434,11 +442,11 @@ - initWithUTF16String: (uint16_t*)string byteOrder: (of_endianess_t)byteOrder length: (size_t)length; /** - * Initializes an already allocated OFString with a format string. + * \brief Initializes an already allocated OFString with a format string. * * See printf for the format syntax. As an addition, %@ is available as format * specifier for objects. * * \param format A string used as format to initialize the OFString @@ -445,11 +453,11 @@ * \return An initialized OFString */ - initWithFormat: (OFConstantString*)format, ...; /** - * Initializes an already allocated OFString with a format string. + * \brief Initializes an already allocated OFString with a format string. * * See printf for the format syntax. As an addition, %@ is available as format * specifier for objects. * * \param format A string used as format to initialize the OFString @@ -458,52 +466,52 @@ */ - initWithFormat: (OFConstantString*)format arguments: (va_list)arguments; /** - * Initializes an already allocated OFString with the constructed specified - * path. + * \brief Initializes an already allocated OFString with the constructed + * specified path. * * \param firstComponent The first component of the path * \return A new autoreleased OFString */ - initWithPath: (OFString*)firstComponent, ...; /** - * Initializes an already allocated OFString with the constructed specified - * path. + * \brief Initializes an already allocated OFString with the constructed + * specified path. * * \param firstComponent The first component of the path * \param arguments A va_list with the other components of the path * \return A new autoreleased OFString */ - initWithPath: (OFString*)firstComponent arguments: (va_list)arguments; /** - * Initializes an already allocated OFString with the contents of the specified - * file in the specified encoding. + * \brief Initializes an already allocated OFString with the contents of the + * specified file in the specified encoding. * * \param path The path to the file * \return An initialized OFString */ - initWithContentsOfFile: (OFString*)path; /** - * Initializes an already allocated OFString with the contents of the specified - * file in the specified encoding. + * \brief Initializes an already allocated OFString with the contents of the + * specified file in the specified encoding. * * \param path The path to the file * \param encoding The encoding of the file * \return An initialized OFString */ - initWithContentsOfFile: (OFString*)path encoding: (of_string_encoding_t)encoding; /** - * Initializes an already allocated OFString with the contents of the specified - * URL. + * \brief Initializes an already allocated OFString with the contents of the + * specified URL. * * If the URL's scheme is file, it tries UTF-8 encoding. * * If the URL's scheme is http(s), it tries to detect the encoding from the HTTP * headers. If it could not detect the encoding using the HTTP headers, it tries @@ -513,215 +521,252 @@ * \return An initialized OFString */ - initWithContentsOfURL: (OFURL*)URL; /** - * Initializes an already allocated OFString with the contents of the specified - * URL in the specified encoding. + * \brief Initializes an already allocated OFString with the contents of the + * specified URL in the specified encoding. * * \param URL The URL to the contents for the string * \param encoding The encoding to assume * \return An initialized OFString */ - initWithContentsOfURL: (OFURL*)URL encoding: (of_string_encoding_t)encoding; /** + * \brief Returns the OFString as a UTF-8 encoded C string. + * * \return The OFString as a UTF-8 encoded C string */ - (const char*)cString; /** + * \brief Returns the length of the string in Unicode characters. + * * \return The length of the string in Unicode characters */ - (size_t)length; /** + * \brief Returns the length of the string which cString would return. + * * \return The length of the string which cString would return */ - (size_t)cStringLength; /** - * Compares the OFString to another OFString without caring about the case. + * \brief Compares the OFString to another OFString without caring about the + * case. * * \param otherString A string to compare with * \return An of_comparison_result_t */ - (of_comparison_result_t)caseInsensitiveCompare: (OFString*)otherString; /** + * \brief Returns the Unicode character at the specified index. + * * \param index The index of the Unicode character to return * \return The Unicode character at the specified index */ - (of_unichar_t)characterAtIndex: (size_t)index; /** + * \brief Returns the index of the first occurrence of the string. + * * \param string The string to search * \return The index of the first occurrence of the string or OF_INVALID_INDEX * if it was not found */ - (size_t)indexOfFirstOccurrenceOfString: (OFString*)string; /** + * \brief Returns the index of the last occurrence of the string. + * * \param string The string to search * \return The index of the last occurrence of the string or OF_INVALID_INDEX if * it was not found */ - (size_t)indexOfLastOccurrenceOfString: (OFString*)string; /** + * \brief Returns whether the string contains the specified string. + * * \param string The string to search * \return Whether the string contains the specified string */ - (BOOL)containsString: (OFString*)string; /** + * \brief Creates a substring with the specified range. + * * \param range The range of the substring * \return The substring as a new autoreleased OFString */ - (OFString*)substringWithRange: (of_range_t)range; /** - * Creates a new string by appending another string. + * \brief Creates a new string by appending another string. * * \param string The string to append * \return A new autoreleased OFString with the specified string appended */ - (OFString*)stringByAppendingString: (OFString*)string; /** - * Creates a new string by prepending another string. + * \brief Creates a new string by prepending another string. * * \param string The string to prepend * \return A new autoreleased OFString with the specified string prepended */ - (OFString*)stringByPrependingString: (OFString*)string; /** - * Creates a new string by replacing the occurrences of the specified string - * with the specified replacement. + * \brief Creates a new string by replacing the occurrences of the specified + * string with the specified replacement. * * \param string The string to replace * \param replacement The string with which it should be replaced * \return A new string with the occurrences of the specified string replaced */ - (OFString*)stringByReplacingOccurrencesOfString: (OFString*)string withString: (OFString*)replacement; /** + * \brief Returns the string in uppercase. + * * \return The string in uppercase */ - (OFString*)uppercaseString; /** + * \brief Returns the string in lowercase. + * * \return The string in lowercase */ - (OFString*)lowercaseString; /** - * Creates a new string by deleting leading whitespaces. + * \brief Creates a new string by deleting leading whitespaces. * * \return A new autoreleased OFString with leading whitespaces deleted */ - (OFString*)stringByDeletingLeadingWhitespaces; /** - * Creates a new string by deleting trailing whitespaces. + * \brief Creates a new string by deleting trailing whitespaces. * * \return A new autoreleased OFString with trailing whitespaces deleted */ - (OFString*)stringByDeletingTrailingWhitespaces; /** - * Creates a new string by deleting leading and trailing whitespaces. + * \brief Creates a new string by deleting leading and trailing whitespaces. * * \return A new autoreleased OFString with leading and trailing whitespaces * deleted */ - (OFString*)stringByDeletingEnclosingWhitespaces; /** - * Checks whether the string has the specified prefix. + * \brief Checks whether the string has the specified prefix. * * \param prefix The prefix to check for * \return A boolean whether the string has the specified prefix */ - (BOOL)hasPrefix: (OFString*)prefix; /** - * Checks whether the string has the specified suffix. + * \brief Checks whether the string has the specified suffix. * * \param suffix The suffix to check for * \return A boolean whether the string has the specified suffix */ - (BOOL)hasSuffix: (OFString*)suffix; /** - * Splits an OFString into an OFArray of OFStrings. + * \brief Splits an OFString into an OFArray of OFStrings. * * \param delimiter The delimiter for splitting * \return An autoreleased OFArray with the split string */ - (OFArray*)componentsSeparatedByString: (OFString*)delimiter; /** + * \brief Returns the components of the path. + * * \return The components of the path */ - (OFArray*)pathComponents; /** + * \brief Returns the last component of the path. + * * \return The last component of the path */ - (OFString*)lastPathComponent; /** + * \brief Returns the directory name of the path. + * * \return The directory name of the path */ - (OFString*)stringByDeletingLastPathComponent; /** - * Returns the decimal value of the string as an intmax_t or throws an - * OFInvalidEncodingException if the string contains any non-number characters. + * \brief Returns the decimal value of the string as an intmax_t. + * * Leading and trailing whitespaces are ignored. + * + * If the string contains any non-number characters, an + * OFInvalidEncodingException is thrown. * * If the number is too big to fit into an intmax_t, an OFOutOfRangeException * is thrown. * * \return An intmax_t with the value of the string */ - (intmax_t)decimalValue; /** - * Returns the hexadecimal value of the string as an uintmax_t or throws an - * OFInvalidEncodingException if the string contains any non-number characters. + * \brief Returns the hexadecimal value of the string as an uintmax_t. + * * Leading and trailing whitespaces are ignored. + * + * If the string contains any non-number characters, an + * OFInvalidEncodingException is thrown. * * If the number is too big to fit into an uintmax_t, an OFOutOfRangeException * is thrown. * * \return A uintmax_t with the value of the string */ - (uintmax_t)hexadecimalValue; /** - * Returns the float value of the string as a float or throws an - * OFInvalidEncodingException if the string contains any non-number characters. + * \brief Returns the float value of the string as a float. + * + * If the string contains any non-number characters, an + * OFInvalidEncodingException is thrown. * * \return A float with the value of the string */ - (float)floatValue; /** - * Returns the double value of the string as a float or throws an - * OFInvalidEncodingException if the string contains any non-number characters. + * \brief Returns the double value of the string as a double. + * + * If the string contains any non-number characters, an + * OFInvalidEncodingException is thrown. * * \return A double with the value of the string */ - (double)doubleValue; /** - * Returns the string as an array of of_unichar_t. + * \brief Returns the string as an array of of_unichar_ts. * * The result is valid until the autorelease pool is released. If you want to * use the result outside the scope of the current autorelease pool, you have to * copy it. * @@ -728,11 +773,11 @@ * \return The string as an array of Unicode characters */ - (of_unichar_t*)unicodeString; /** - * Writes the string into the specified file using UTF-8 encoding. + * \brief Writes the string into the specified file using UTF-8 encoding. * * \param path The path of the file to write to */ - (void)writeToFile: (OFString*)path; @end Index: src/OFTCPSocket.h ================================================================== --- src/OFTCPSocket.h +++ src/OFTCPSocket.h @@ -40,20 +40,20 @@ struct sockaddr_storage *sockAddr; socklen_t sockAddrLen; } /** - * Connect the OFTCPSocket to the specified destination. + * \brief Connect the OFTCPSocket to the specified destination. * * \param host The host to connect to * \param port The port on the host to connect to */ - (void)connectToHost: (OFString*)host port: (uint16_t)port; /** - * Bind the socket on the specified port and host. + * \brief Bind the socket on the specified port and host. * * \param port The port to bind to. If the port is 0, an unused port will be * chosen, which can be obtained using the return value. * \param host The host to bind to. Use @"0.0.0.0" for IPv4 or @"::" for IPv6 * to bind to all. @@ -61,39 +61,46 @@ */ - (uint16_t)bindToPort: (uint16_t)port onHost: (OFString*)host; /** - * Listen on the socket. + * \brief Listen on the socket. * * \param backlog Maximum length for the queue of pending connections. */ - (void)listenWithBackLog: (int)backLog; /** - * Listen on the socket. + * \brief Listen on the socket. */ - (void)listen; /** - * Accept an incoming connection. + * \brief Accept an incoming connection. + * * \return An autoreleased OFTCPSocket for the accepted connection. */ - (OFTCPSocket*)accept; /** - * Enable or disable keep alives for the connection. + * \brief Enable or disable keep alives for the connection. + * + * \param enable Whether to enable or disable keep alives for the connection */ - (void)setKeepAlivesEnabled: (BOOL)enable; /** - * Returns the remote address of the socket. Only works with accepted sockets! + * \brief Returns the remote address of the socket. + * + * Only works with accepted sockets! * * \return The remote address as a string */ - (OFString*)remoteAddress; /** + * \brief Returns whether the socket is a listening socket. + * * \return Whether the socket is a listening socket */ - (BOOL)isListening; @end Index: src/OFThread.h ================================================================== --- src/OFThread.h +++ src/OFThread.h @@ -41,28 +41,30 @@ of_list_object_t *listObject; BOOL initialized; } /** - * \return A new autoreleased Thread Local Storage key + * \brief Creates a new Thread Local Storage key + * + * \return A new, autoreleased Thread Local Storage key */ + TLSKey; /** + * \brief Creates a new Thread Local Storage key with the specified destructor. + * * \param destructor A destructor that is called when the thread is terminated * \return A new autoreleased Thread Local Storage key */ + TLSKeyWithDestructor: (void(*)(id))destructor; + (void)callAllDestructors; /** - * \return An initialized Thread Local Storage key - */ -- init; - -/** + * \brief Initializes an already allocated Thread Local Storage Key with the + * specified destructor. + * * \param destructor A destructor that is called when the thread is terminated * \return An initialized Thread Local Storage key */ - initWithDestructor: (void(*)(id))destructor; @end @@ -92,38 +94,46 @@ #if defined(OF_HAVE_PROPERTIES) && defined(OF_HAVE_BLOCKS) @property (retain) of_thread_block_t block; #endif /** + * \brief Creates a new thread. + * * \return A new, autoreleased thread */ + thread; /** + * \brief Creates a new thread with the specified object. + * * \param object An object which is passed for use in the main method or nil * \return A new, autoreleased thread */ + threadWithObject: (id)object; #ifdef OF_HAVE_BLOCKS /** + * \brief Creates a new thread with the specified block. + * * \param block A block which is executed by the thread * \return A new, autoreleased thread */ + threadWithBlock: (of_thread_block_t)block; /** + * \brief Creates a new thread with the specified block and object. + * * \param block A block which is executed by the thread * \param object An object which is passed for use in the main method or nil * \return A new, autoreleased thread */ + threadWithBlock: (of_thread_block_t)block object: (id)object; #endif /** - * Sets the Thread Local Storage for the specified key. + * \brief Sets the Thread Local Storage for the specified key. * * The specified object is first retained and then the object stored before is * released. You can specify nil as object if you want the old object to be * released and don't want any new object for the TLS key. * @@ -132,108 +142,121 @@ */ + (void)setObject: (id)object forTLSKey: (OFTLSKey*)key; /** - * Returns the object for the specified Thread Local Storage key. + * \brief Returns the object for the specified Thread Local Storage key. * * The returned object is not retained and autoreleased for performance * reasons! * * \param key The Thread Local Storage key */ + (id)objectForTLSKey: (OFTLSKey*)key; /** + * \brief Returns the current thread. + * * \return The current thread or nil if we are in the main thread */ + (OFThread*)currentThread; /** - * Suspends execution of the current thread for the specified time interval. + * \brief Suspends execution of the current thread for the specified time + * interval. * * \param seconds The number of seconds to sleep */ + (void)sleepForTimeInterval: (int64_t)seconds; /** - * Suspends execution of the current thread for the specified time interval. + * \brief Suspends execution of the current thread for the specified time + * interval. * * \param seconds The number of seconds to sleep * \param microseconds The number of microseconds to sleep */ + (void)sleepForTimeInterval: (int64_t)seconds microseconds: (uint32_t)microseconds; /** - * Suspends execution of the current thread until the specified date. + * \brief Suspends execution of the current thread until the specified date. + * + * \param date The date to wait for */ + (void)sleepUntilDate: (OFDate*)date; /** - * Yields a processor voluntarily and moves the thread at the end of the queue - * for its priority. + * \brief Yields a processor voluntarily and moves the thread at the end of the + * queue for its priority. */ + (void)yield; /** - * Terminates the current thread, letting it return nil. + * \brief Terminates the current thread, letting it return nil. */ + (void)terminate; /** - * Terminates the current thread, letting it return the specified object. + * \brief Terminates the current thread, letting it return the specified object. * * \param object The object which the terminated thread will return */ + (void)terminateWithObject: (id)object; /** + * \brief Initializes an already allocated thread with the specified object. + * * \param object An object which is passed for use in the main method or nil * \return An initialized OFThread. */ - initWithObject: (id)object; #ifdef OF_HAVE_BLOCKS /** + * \brief Initializes an already allocated thread with the specified block. + * * \param block A block which is executed by the thread * \return An initialized OFThread. */ - initWithBlock: (of_thread_block_t)block; /** + * \brief Initializes an already allocated thread with the specified block and + * object. + * * \param block A block which is executed by the thread * \param object An object which is passed for use in the main method or nil * \return An initialized OFThread. */ - initWithBlock: (of_thread_block_t)block object: (id)object; #endif /** - * The main routine of the thread. You need to reimplement this! + * \brief The main routine of the thread. You need to reimplement this! * * It can access the object passed to the threadWithObject or initWithObject * method using the instance variable named object. * * \return The object the join method should return when called for this thread */ - (id)main; /** - * This routine is exectued when the thread's main method has finished executing - * or terminate has been called. + * \brief This routine is exectued when the thread's main method has finished + * executing or terminate has been called. */ - (void)handleTermination; /** - * Starts the thread. + * \brief Starts the thread. */ - (void)start; /** - * Joins a thread. + * \brief Joins a thread. * * \return The object returned by the main method of the thread. */ - (id)join; @end @@ -246,29 +269,30 @@ of_mutex_t mutex; BOOL initialized; } /** + * \brief Creates a new mutex. + * * \return A new autoreleased mutex. */ + mutex; /** - * Locks the mutex. + * \brief Locks the mutex. */ - (void)lock; /** - * Tries to lock the mutex and returns a boolean whether the mutex could be - * acquired. + * \brief Tries to lock the mutex. * * \return A boolean whether the mutex could be acquired */ - (BOOL)tryLock; /** - * Unlocks the mutex. + * \brief Unlocks the mutex. */ - (void)unlock; @end /** @@ -279,25 +303,27 @@ of_condition_t condition; BOOL conditionInitialized; } /** + * \brief Creates a new condition. + * * \return A new, autoreleased OFCondition */ + condition; /** - * Blocks the current thread until another thread calls -[signal] or - * -[broadcast]. + * \brief Blocks the current thread until another thread calls -[signal] or + * -[broadcast]. */ - (void)wait; /** - * Signals the next waiting thread to continue. + * \brief Signals the next waiting thread to continue. */ - (void)signal; /** - * Signals all threads to continue. + * \brief Signals all threads to continue. */ - (void)broadcast; @end Index: src/OFURL.h ================================================================== --- src/OFURL.h +++ src/OFURL.h @@ -46,144 +46,167 @@ @property (copy) OFString *query; @property (copy) OFString *fragment; #endif /** + * Creates a new URL with the specified string. + * * \param string A string describing a URL * \return A new, autoreleased OFURL */ + URLWithString: (OFString*)string; /** + * Creates a new URL with the specified string relative to the specified URL. + * * \param string A string describing a URL * \param URL An URL to which the string is relative * \return A new, autoreleased OFURL */ + URLWithString: (OFString*)string relativeToURL: (OFURL*)URL; /** - * Initializes an already allocated OFURL. + * \brief Initializes an already allocated OFURL with the specified string. * * \param string A string describing a URL * \return An initialized OFURL */ - initWithString: (OFString*)string; /** - * Initializes an already allocated OFURL. + * \brief Initializes an already allocated OFURL with the specified string and + * relative URL. * * \param string A string describing a URL * \param URL A URL to which the string is relative * \return An initialized OFURL */ - initWithString: (OFString*)string relativeToURL: (OFURL*)url; /** + * \brief Returns the scheme part of the URL. + * * \return The scheme part of the URL */ - (OFString*)scheme; /** - * Set the scheme part of the URL. + * \brief Set the scheme part of the URL. * * \param scheme The scheme part of the URL to set */ - (void)setScheme: (OFString*)scheme; /** + * \brief Returns the host part of the URL. + * * \return The host part of the URL */ - (OFString*)host; /** - * Set the host part of the URL. + * \brief Set the host part of the URL. * * \param host The host part of the URL to set */ - (void)setHost: (OFString*)host; /** + * \brief Returns the port part of the URL. + * * \return The port part of the URL */ - (uint16_t)port; /** - * Set the port part of the URL. + * \brief Set the port part of the URL. * * \param port The port part of the URL to set */ - (void)setPort: (uint16_t)port; /** + * \brief Returns the user part of the URL. + * * \return The user part of the URL */ - (OFString*)user; /** - * Set the user part of the URL. + * \brief Set the user part of the URL. * * \param user The user part of the URL to set */ - (void)setUser: (OFString*)user; /** + * \brief Returns the password part of the URL. + * * \return The password part of the URL */ - (OFString*)password; /** - * Set the password part of the URL. + * \brief Set the password part of the URL. * * \param password The password part of the URL to set */ - (void)setPassword: (OFString*)password; /** + * \brief Returns the path part of the URL. + * * \return The path part of the URL */ - (OFString*)path; /** - * Set the path part of the URL. + * \brief Set the path part of the URL. * * \param path The path part of the URL to set */ - (void)setPath: (OFString*)path; /** + * \brief Returns the parameters part of the URL. + * * \return The parameters part of the URL */ - (OFString*)parameters; /** - * Set the parameters part of the URL. + * \brief Set the parameters part of the URL. * * \param parameters The parameters part of the URL to set */ - (void)setParameters: (OFString*)parameters; /** + * \brief Returns the query part of the URL. + * * \return The query part of the URL */ - (OFString*)query; /** - * Set the query part of the URL. + * \brief Set the query part of the URL. * * \param query The query part of the URL to set */ - (void)setQuery: (OFString*)query; /** + * \brief Returns the fragment part of the URL. + * * \return The fragment part of the URL */ - (OFString*)fragment; /** - * Set the fragment part of the URL. + * \brief Set the fragment part of the URL. * * \param fragment The fragment part of the URL to set */ - (void)setFragment: (OFString*)fragment; Index: src/OFXMLAttribute.h ================================================================== --- src/OFXMLAttribute.h +++ src/OFXMLAttribute.h @@ -35,10 +35,12 @@ @property (readonly, retain, getter=namespace) OFString *ns; @property (readonly, retain) OFString *stringValue; #endif /** + * \brief Creates a new XML attribute. + * * \param name The name of the attribute * \param ns The namespace of the attribute * \param value The string value of the attribute * \return A new autoreleased OFXMLAttribute with the specified parameters */ @@ -45,11 +47,11 @@ + attributeWithName: (OFString*)name namespace: (OFString*)ns stringValue: (OFString*)value; /** - * Initializes an already allocated OFXMLAttribute. + * \brief Initializes an already allocated OFXMLAttribute. * * \param name The name of the attribute * \param ns The namespace of the attribute * \param value The string value of the attribute * \return An initialized OFXMLAttribute with the specified parameters @@ -57,39 +59,53 @@ - initWithName: (OFString*)name namespace: (OFString*)ns stringValue: (OFString*)value; /** + * \brief Returns the name of the attribute as an autoreleased OFString. + * * \return The name of the attribute as an autoreleased OFString */ - (OFString*)name; /** + * \brief Returns the namespace of the attribute as an autoreleased OFString. + * * \return The namespace of the attribute as an autoreleased OFString */ - (OFString*)namespace; /** + * \brief Returns the string value of the attribute as an autoreleased OFString. + * * \return The string value of the attribute as an autoreleased OFString */ - (OFString*)stringValue; /** + * \brief Returns an integer with the decimal value of the attribute. + * * \return An integer with the decimal value of the attribute */ - (intmax_t)decimalValue; /** + * \brief Returns an integer with the hexadecimal value of the attribute. + * * \return An integer with the hexadecimal value of the attribute */ - (uintmax_t)hexadecimalValue; /** + * \brief Returns a float with the float value of the attribute. + * * \return A float with the float value of the attribute */ - (float)floatValue; /** + * \brief Returns a double with the double value of the attribute. + * * \return A double with the double value of the attribute */ - (double)doubleValue; @end Index: src/OFXMLElement.h ================================================================== --- src/OFXMLElement.h +++ src/OFXMLElement.h @@ -47,34 +47,43 @@ @property (readonly, copy) OFArray *attributes; @property (readonly, copy) OFArray *children; #endif /** + * \brief Creates a new XML element with the specified name. + * * \param name The name for the element * \return A new autoreleased OFXMLElement with the specified element name */ + elementWithName: (OFString*)name; /** + * \brief Creates a new XML element with the specified name and string value. + * * \param name The name for the element * \param stringValue The value for the element * \return A new autoreleased OFXMLElement with the specified element name and * value */ + elementWithName: (OFString*)name stringValue: (OFString*)stringValue; /** + * \brief Creates a new XML element with the specified name and namespace. + * * \param name The name for the element * \param ns The namespace for the element * \return A new autoreleased OFXMLElement with the specified element name and * namespace */ + elementWithName: (OFString*)name namespace: (OFString*)ns; /** + * \brief Creates a new XML element with the specified name, namespace and + * string value. + * * \param name The name for the element * \param ns The namespace for the element * \param stringValue The value for the element * \return A new autoreleased OFXMLElement with the specified element name, * namespace and value @@ -82,70 +91,71 @@ + elementWithName: (OFString*)name namespace: (OFString*)ns stringValue: (OFString*)stringValue; /** - * Creates a new element, only consisting of the specified characters. + * \brief Creates a new element with the specified characters. * * \param characters The characters the element represents * \return A new autoreleased OFXMLElement consisting of the specified * characters */ + elementWithCharacters: (OFString*)characters; /** - * Creates a new element, only consisting of the specified CDATA. + * \brief Creates a new element with the specified CDATA. * * \param CDATA The CDATA the element represents * \return A new autoreleased OFXMLElement consisting of the specified CDATA */ + elementWithCDATA: (OFString*)CDATA; /** - * Creates a new element, only consisting of the specified comment. + * \brief Creates a new element with the specified comment. * * \param comment The comment the element represents * \return A new autoreleased OFXMLElement consisting of the specified comment */ + elementWithComment: (OFString*)comment; /** + * \brief Creates a new element with the specified element. + * * \param element An OFXMLElement to initialize the OFXMLElement with * \return A new autoreleased OFXMLElement with the contents of the specified * element */ + elementWithElement: (OFXMLElement*)element; /** - * Parses the string and returns an OFXMLElement for it. + * \brief Parses the string and returns an OFXMLElement for it. * * \param string The string to parse * \return A new autoreleased OFXMLElement with the contents of the string */ + elementWithXMLString: (OFString*)string; /** - * Parses the specified file and returns an OFXMLElement for it. + * \brief Parses the specified file and returns an OFXMLElement for it. * * \param path The path to the file * \return A new autoreleased OFXMLElement with the contents of the specified * file */ + elementWithFile: (OFString*)path; /** - * Initializes an already allocated OFXMLElement with the specified element - * name. + * \brief Initializes an already allocated OFXMLElement with the specified name. * * \param name The name for the element * \return An initialized OFXMLElement with the specified element name */ - initWithName: (OFString*)name; /** - * Initializes an already allocated OFXMLElement with the specified element - * name and value. + * \brief Initializes an already allocated OFXMLElement with the specified name + * and string value. * * \param name The name for the element * \param stringValue The value for the element * \return An initialized OFXMLElement with the specified element name and * value @@ -152,12 +162,12 @@ */ - initWithName: (OFString*)name stringValue: (OFString*)stringValue; /** - * Initializes an already allocated OFXMLElement with the specified element - * name and namespace. + * \brief Initializes an already allocated OFXMLElement with the specified name + * and namespace. * * \param name The name for the element * \param ns The namespace for the element * \return An initialized OFXMLElement with the specified element name and * namespace @@ -164,12 +174,12 @@ */ - initWithName: (OFString*)name namespace: (OFString*)ns; /** - * Initializes an already allocated OFXMLElement with the specified element - * name, namespace and value. + * \brief Initializes an already allocated OFXMLElement with the specified name, + * namespace and value. * * \param name The name for the element * \param ns The namespace for the element * \param stringValue The value for the element * \return An initialized OFXMLElement with the specified element name, @@ -178,161 +188,187 @@ - initWithName: (OFString*)name namespace: (OFString*)ns stringValue: (OFString*)stringValue; /** - * Initializes an already allocated OFXMLElement so that it only consists of the - * specified characters. + * \brief Initializes an already allocated OFXMLElement with the specified + * characters. * * \param characters The characters the element represents * \return An initialized OFXMLElement consisting of the specified characters */ - initWithCharacters: (OFString*)characters; /** - * Initializes an already allocated OFXMLElement so that it only consists of the - * specified CDATA. + * \brief Initializes an already allocated OFXMLElement with the specified + * CDATA. * * \param CDATA The CDATA the element represents * \return An initialized OFXMLElement consisting of the specified CDATA */ - initWithCDATA: (OFString*)CDATA; /** - * Initializes an already allocated OFXMLElement so that it only consists of the - * specified comment. + * \brief Initializes an already allocated OFXMLElement with the specified + * comment. * * \param comment The comment the element represents * \return An initialized OFXMLElement consisting of the specified comment */ - initWithComment: (OFString*)comment; /** - * Initializes an already allocated OFXMLElement with the specified - * OFXMLElement. + * \brief Initializes an already allocated OFXMLElement with the specified + * element. * * \param element An OFXMLElement to initialize the OFXMLElement with * \return A new autoreleased OFXMLElement with the contents of the specified * element */ - initWithElement: (OFXMLElement*)element; /** - * Parses the string and initializes an already allocated OFXMLElement with it. + * \brief Parses the string and initializes an already allocated OFXMLElement + * with it. * * \param string The string to parse * \return An initialized OFXMLElement with the contents of the string */ - initWithXMLString: (OFString*)string; /** - * Parses the specified file and initializes an already allocated OFXMLElement - * with it. + * \brief Parses the specified file and initializes an already allocated + * OFXMLElement with it. * * \param path The path to the file * \return An initialized OFXMLElement with the contents of the specified file */ - initWithFile: (OFString*)path; /** - * Sets the name of the element. + * \brief Sets the name of the element. * * \param name The new name */ - (void)setName: (OFString*)name; /** + * \brief Returns the name of the element. + * * \return The name of the element */ - (OFString*)name; /** - * Sets the namespace of the element. + * \brief Sets the namespace of the element. * * \param ns The new namespace */ - (void)setNamespace: (OFString*)ns; /** + * \brief Returns the namespace of the element. + * * \return The namespace of the element */ - (OFString*)namespace; /** + * \brief Returns an OFArray with the attributes of the element. + * * \return An OFArray with the attributes of the element */ - (OFArray*)attributes; /** - * Removes all children and adds the children from the specified array. + * \brief Removes all children and adds the children from the specified array. * * \param children The new children to add */ - (void)setChildren: (OFArray*)children; /** + * \brief Returns an array with all children of the element. + * * \return An array with all children of the element */ - (OFArray*)children; /** - * Removes all children and sets the string value to the specified string. + * \brief Removes all children and sets the string value to the specified + * string. * * \param stringValue The new string value for the element */ - (void)setStringValue: (OFString*)stringValue; /** + * \brief Returns a string with the string value of all children concatenated. + * * \return A string with the string value of all children concatenated */ - (OFString*)stringValue; /** + * \brief Returns an integer with the decimal value of all children + * concatenated. + * * \return An integer with the decimal value of all children concatenated */ - (intmax_t)decimalValue; /** + * \brief Returns an integer with the hexadecimal value of all children + * concatenated. + * * \return An integer with the hexadecimal value of all children concatenated */ - (uintmax_t)hexadecimalValue; /** + * \brief Returns a float with the float value of all children concatenated. + * * \return A float with the float value of all children concatenated */ - (float)floatValue; /** + * \brief Returns a double with the double value of all children concatenated. + * * \return A double with the double value of all children concatenated */ - (double)doubleValue; /** - * \return A new autoreleased OFString representing the OFXMLElement as an - * XML string + * \brief Returns an OFString representing the OFXMLElement as an XML string. + * + * \return An OFString representing the OFXMLElement as an XML string */ - (OFString*)XMLString; /** + * \brief Returns an OFString representing the OFXMLElement as an XML string + * with indentation. + * * \param indentation The indentation for the XML string - * \return A new autoreleased OFString representing the OFXMLElement as an - * XML string with indentation. + * \return An OFString representing the OFXMLElement as an XML string with + * indentation */ - (OFString*)XMLStringWithIndentation: (unsigned int)indentation; /** - * Adds the specified attribute. + * \brief Adds the specified attribute. * * If an attribute with the same name and namespace already exists, it is not * added. * * \param attribute The attribute to add */ - (void)addAttribute: (OFXMLAttribute*)attribute; /** - * Adds the specified attribute with the specified value. + * \brief Adds the specified attribute with the specified string value. * * If an attribute with the same name and namespace already exists, it is not * added. * * \param name The name of the attribute @@ -340,11 +376,12 @@ */ - (void)addAttributeWithName: (OFString*)name stringValue: (OFString*)stringValue; /** - * Adds the specified attribute with the specified namespace and value. + * \brief Adds the specified attribute with the specified namespace and string + * value. * * If an attribute with the same name and namespace already exists, it is not * added. * * \param name The name of the attribute @@ -354,117 +391,130 @@ - (void)addAttributeWithName: (OFString*)name namespace: (OFString*)ns stringValue: (OFString*)stringValue; /** + * \brief Returns the attribute with the specified name. + * * \param attributeName The name of the attribute * \return The attribute with the specified name */ - (OFXMLAttribute*)attributeForName: (OFString*)attributeName; /** + * \brief Returns the attribute with the specified name and namespace. + * * \param attributeName The name of the attribute * \param attributeNS The namespace of the attribute * \return The attribute with the specified name and namespace */ - (OFXMLAttribute*)attributeForName: (OFString*)attributeName namespace: (OFString*)attributeNS; /** - * Removes the attribute with the specified name. + * \brief Removes the attribute with the specified name. * * \param attribteName The name of the attribute */ - (void)removeAttributeForName: (OFString*)attributeName; /** - * Removes the attribute with the specified name and namespace. + * \brief Removes the attribute with the specified name and namespace. * * \param attributeName The name of the attribute * \param attributeNS The namespace of the attribute */ - (void)removeAttributeForName: (OFString*)attributeName namespace: (OFString*)attributeNS; /** - * Sets a prefix for a namespace. + * \brief Sets a prefix for a namespace. * * \param prefix The prefix for the namespace * \param ns The namespace for which the prefix is set */ - (void)setPrefix: (OFString*)prefix forNamespace: (OFString*)ns; /** - * Binds a prefix for a namespace. + * \brief Binds a prefix for a namespace. * * \param prefix The prefix for the namespace * \param ns The namespace for which the prefix is bound */ - (void)bindPrefix: (OFString*)prefix forNamespace: (OFString*)ns; /** - * Sets the default namespace for the element to be used if there is no parent. + * \brief Sets the default namespace for the element to be used if there is no + * parent. * * \param ns The default namespace for the element */ - (void)setDefaultNamespace: (OFString*)ns; /** - * Adds a child to the OFXMLElement. + * \brief Adds a child to the OFXMLElement. * * \param child Another OFXMLElement which is added as a child */ - (void)addChild: (OFXMLElement*)child; /** - * Removes the first child that is equal to the specified OFXMLElement. + * \brief Removes the first child that is equal to the specified OFXMLElement. * * \param child The child to remove from the OFXMLElement */ - (void)removeChild: (OFXMLElement*)child; /** - * Returns all children that are elements. + * \brief Returns all children that are elements. * * \return All children that are elements */ - (OFArray*)elements; /** - * Returns all children that have the specified namespace. + * \brief Returns all children that have the specified namespace. * * \return All children that have the specified namespace */ - (OFArray*)elementsForNamespace: (OFString*)elementNS; /** + * \brief Returns the first child element with the specified name. + * * \param elementName The name of the element * \return The first child element with the specified name */ - (OFXMLElement*)elementForName: (OFString*)elementName; /** + * \brief Returns the child elements with the specified name. + * * \param elementName The name of the elements * \return The child elements with the specified name */ - (OFArray*)elementsForName: (OFString*)elementName; /** + * \brief Returns the first child element with the specified name and namespace. + * * \param elementName The name of the element * \param elementNS The namespace of the element * \return The first child element with the specified name and namespace */ - (OFXMLElement*)elementForName: (OFString*)elementName namespace: (OFString*)elementNS; /** + * \brief Returns the child elements with the specified name and namespace. + * * \param elementName The name of the elements * \param elementNS The namespace of the elements * \return The child elements with the specified name and namespace */ - (OFArray*)elementsForName: (OFString*)elementName namespace: (OFString*)elementNS; @end #import "OFXMLElement+Serialization.h" Index: src/OFXMLElementBuilder.h ================================================================== --- src/OFXMLElementBuilder.h +++ src/OFXMLElementBuilder.h @@ -29,11 +29,11 @@ @protocol OFXMLElementBuilderDelegate #else @protocol OFXMLElementBuilderDelegate #endif /** - * This callback is called when the OFXMLElementBuilder built an element. + * \brief This callback is called when the OFXMLElementBuilder built an element. * * If the OFXMLElementBuilder was used as a delegate for the OFXMLParser since * parsing started, this will return the complete document as an OFXMLElement * with all children. * @@ -45,12 +45,12 @@ #ifdef OF_HAVE_OPTIONAL_PROTOCOLS @optional #endif /** - * This callback is called when the OFXMLElementBuilder gets a close tag which - * does not belong there. + * \brief This callback is called when the OFXMLElementBuilder gets a close tag + * which does not belong there. * * Most likely, the OFXMLElementBuilder was used to build XML only of a child * of the root element and the root element was closed. Often the delegate is * set to the OFXMLElementBuilder when a certain element is found, this can be * used then to set the delegate back after that certain element has been @@ -68,12 +68,12 @@ didNotExpectCloseTag: (OFString*)name withPrefix: (OFString*)prefix namespace: (OFString*)ns; /** - * This callback is called when the XML parser for the element builder found an - * unknown entity. + * \brief This callback is called when the XML parser for the element builder + * found an unknown entity. * * \param entity The name of the entity * \return The substitution for the entity */ - (OFString*)elementBuilder: (OFXMLElementBuilder*)builder @@ -97,24 +97,28 @@ #ifdef OF_HAVE_PROPERTIES @property (retain) id delegate; #endif /** + * \brief Creates a new element builder. + * * \return A new, autoreleased OFXMLElementBuilder */ + elementBuilder; /** + * \brief Returns the delegate for the OFXMLElementBuilder. + * * \return The delegate for the OFXMLElementBuilder */ - (id )delegate; /** - * Sets the delegate for the OFXMLElementBuilder. + * \brief Sets the delegate for the OFXMLElementBuilder. * * \param delegate The delegate for the OFXMLElementBuilder */ - (void)setDelegate: (id )delegate; @end @interface OFObject (OFXMLElementBuilderDelegate) @end Index: src/OFXMLParser.h ================================================================== --- src/OFXMLParser.h +++ src/OFXMLParser.h @@ -34,20 +34,22 @@ #endif #ifdef OF_HAVE_OPTIONAL_PROTOCOLS @optional #endif /** - * This callback is called when the XML parser found processing instructions. + * \brief This callback is called when the XML parser found processing + * instructions. * * \param parser The parser which found processing instructions * \param pi The processing instructions */ - (void)parser: (OFXMLParser*)parser foundProcessingInstructions: (OFString*)pi; /** - * This callback is called when the XML parser found the start of a new tag. + * \brief This callback is called when the XML parser found the start of a new + * tag. * * \param parser The parser which found a new tag * \param name The name of the tag which just started * \param prefix The prefix of the tag which just started or nil * \param ns The namespace of the tag which just started or nil @@ -59,11 +61,11 @@ withPrefix: (OFString*)prefix namespace: (OFString*)ns attributes: (OFArray*)attributes; /** - * This callback is called when the XML parser found the end of a tag. + * \brief This callback is called when the XML parser found the end of a tag. * * \param parser The parser which found the end of a tag * \param name The name of the tag which just ended * \param prefix The prefix of the tag which just ended or nil * \param ns The namespace of the tag which just ended or nil @@ -72,11 +74,11 @@ didEndElement: (OFString*)name withPrefix: (OFString*)prefix namespace: (OFString*)ns; /** - * This callback is called when the XML parser found characters. + * \brief This callback is called when the XML parser found characters. * * In case there are comments or CDATA, it is possible that this callback is * called multiple times in a row. * * \param parser The parser which found a string @@ -84,29 +86,31 @@ */ - (void)parser: (OFXMLParser*)parser foundCharacters: (OFString*)characters; /** - * This callback is called when the XML parser found CDATA. + * \brief This callback is called when the XML parser found CDATA. * * \param parser The parser which found a string * \param CDATA The CDATA the XML parser found */ - (void)parser: (OFXMLParser*)parser foundCDATA: (OFString*)CDATA; /** - * This callback is called when the XML parser found a comment. + * \brief This callback is called when the XML parser found a comment. * * \param parser The parser which found a comment * \param comment The comment the XML parser found */ - (void)parser: (OFXMLParser*)parser foundComment: (OFString*)comment; /** - * This callback is called when the XML parser found an entity it doesn't know. + * \brief This callback is called when the XML parser found an entity it + * doesn't know. + * * The callback is supposed to return a substitution for the entity or nil if * it is not known to the callback as well, in which case an exception will be * risen. * * \param parser The parser which found an unknown entity @@ -168,64 +172,72 @@ #ifdef OF_HAVE_PROPERTIES @property (retain) id delegate; #endif /** + * \brief Creates a new XML parser. + * * \return A new, autoreleased OFXMLParser */ + parser; /** + * \brief Returns the delegate that is used by the XML parser. + * * \return The delegate that is used by the XML parser */ - (id )delegate; /** - * Sets the delegate the OFXMLParser should use. + * \brief Sets the delegate the OFXMLParser should use. * * \param delegate The delegate to use */ - (void)setDelegate: (id )delegate; /** - * Parses a buffer with the specified size. + * \brief Parses the specified buffer with the specified size. * * \param buffer The buffer to parse * \param length The length of the buffer */ - (void)parseBuffer: (const char*)buffer withLength: (size_t)length; /** - * Parses the specified string. + * \brief Parses the specified string. * * \param string The string to parse */ - (void)parseString: (OFString*)string; /** - * Parses the specified stream. + * \brief Parses the specified stream. * * \param stream The stream to parse */ - (void)parseStream: (OFStream*)stream; /** - * Parses the specified file. + * \brief Parses the specified file. * * \param path The path to the file to parse */ - (void)parseFile: (OFString*)path; /** + * \brief Returns the current line number. + * * \return The current line number */ - (size_t)lineNumber; /** + * \brief Returns whether the XML parser has finished parsing. + * * \return Whether the XML parser has finished parsing */ - (BOOL)finishedParsing; @end @interface OFObject (OFXMLParserDelegate) @end