Index: src/OFCondition.h ================================================================== --- src/OFCondition.h +++ src/OFCondition.h @@ -31,12 +31,12 @@ * \return A new, autoreleased OFCondition */ + (instancetype)condition; /** - * \brief Blocks the current thread until another thread calls -[signal] or - * -[broadcast]. + * \brief Blocks the current thread until another thread calls \ref signal or + * \ref broadcast. */ - (void)wait; /** * \brief Signals the next waiting thread to continue. Index: src/OFDataArray.h ================================================================== --- src/OFDataArray.h +++ src/OFDataArray.h @@ -91,17 +91,10 @@ * \param string The string with the Base64-encoded data * \return A new autoreleased OFDataArray */ + (instancetype)dataArrayWithBase64EncodedString: (OFString*)string; -/** - * \brief Initializes an already allocated OFDataArray with an item size of 1. - * - * \return A initialized OFDataArray - */ -- init; - /** * \brief Initializes an already allocated OFDataArray whose items all have the * same size. * * \param itemSize The size of each element in the OFDataArray @@ -139,11 +132,11 @@ /** * \brief Initializes an already allocated OFDataArray with an item size of 1, * containing the data of the Base64-encoded string. * * \param string The string with the Base64-encoded data - * \return A initialized OFDataArray + * \return An initialized OFDataArray */ - initWithBase64EncodedString: (OFString*)string; /** * \brief Returns the number of items in the OFDataArray. Index: src/OFDate.h ================================================================== --- src/OFDate.h +++ src/OFDate.h @@ -54,11 +54,11 @@ /** * \brief Creates a new OFDate with the specified string in the specified * format. * - * The time zone used is UTC. See +[dateWithLocalDateString:format:] if you + * The time zone used is UTC. See \ref dateWithLocalDateString:format: if you * want local time. * * See the manpage for strftime for information on the format. * * \warning The format is currently limited to the following format specifiers: @@ -126,11 +126,11 @@ /** * \brief Initializes an already allocated OFDate with the specified string in * the specified format. * * The time zone used is UTC. If a time zone is specified anyway, an - * OFInvalidFormatException is thrown. See -[initWithLocalDateString:format:] + * OFInvalidFormatException is thrown. See \ref initWithLocalDateString:format: * if you want to specify a time zone. * * See the manpage for strftime for information on the format. * * \warning The format is currently limited to the following format specifiers: Index: src/OFDictionary.h ================================================================== --- src/OFDictionary.h +++ src/OFDictionary.h @@ -101,17 +101,10 @@ * \param firstKey The first key * \return A new autoreleased OFDictionary */ + (instancetype)dictionaryWithKeysAndObjects: (id)firstKey, ... OF_SENTINEL; -/** - * \brief Initializes an already allocated OFDictionary. - * - * \return An initialized OFDictionary - */ -- init; - /** * \brief Initializes an already allocated OFDictionary with the specified * OFDictionary. * * \param dictionary An OFDictionary Index: src/OFObject.h ================================================================== --- src/OFObject.h +++ src/OFObject.h @@ -370,11 +370,11 @@ * \return The allocated object */ + alloc; /** - * \brief Allocates memory for a new instance and calls -[init] on it. + * \brief Allocates memory for a new instance and calls \ref init on it. * \return An allocated and initialized object */ + new; /** @@ -546,13 +546,17 @@ + (BOOL)resolveInstanceMethod: (SEL)selector; /** * \brief Initializes an already allocated object. * - * Derived classes may override this, but need to do self = [super init] before - * they do any initialization themselves. init may never return nil, instead - * an exception (for example OFInitializationFailed) should be thrown. + * Derived classes may override this, but need to do + * \code + * self = [super init] + * \endcode + * before they do any initialization themselves. \ref init may never return nil, + * instead an exception (for example OFInitializationFailedException) should be + * thrown. * * \return An initialized object */ - init; Index: src/OFSeekableStream.h ================================================================== --- src/OFSeekableStream.h +++ src/OFSeekableStream.h @@ -26,17 +26,17 @@ #import "OFStream.h" /** * \brief A stream that supports seeking. * - * \note If you want to subclass this, override lowlevelSeekToOffset:, - * lowlevelSeekForwardWithOffset: and lowlevelSeekToOffsetRelativeToEnd:, - * but nothing else, as they do the actual work. OFSeekableStream uses - * those and makes them work together with the caching of OFStream. - * If you override these methods without the lowlevel prefix, you - * will break caching, get broken results and seek to the wrong - * position! + * \note If you want to subclass this, override \ref lowlevelSeekToOffset:, + * \ref lowlevelSeekForwardWithOffset: and + * \ref lowlevelSeekToOffsetRelativeToEnd:, but nothing else, as they do + * the actual work. OFSeekableStream uses those and makes them work + * together with the caching of OFStream. If you override these methods + * without the lowlevel prefix, you will break caching, get broken + * results and seek to the wrong position! */ @interface OFSeekableStream: OFStream /** * \brief Seeks to the specified absolute offset. * Index: src/OFStream.h ================================================================== --- src/OFStream.h +++ src/OFStream.h @@ -45,16 +45,17 @@ * retains it. This is so that the stream can be used as a key for a * dictionary, so context can be associated with a stream. Using a * stream in more than one thread at the same time is not thread-safe, * even if copy was called to create one "instance" for every thread! * - * \note If you want to subclass this, override lowlevelReadIntoBuffer:length:, - * lowlevelWriteBuffer:length: and lowlevelIsAtEndOfStream, but nothing - * else, as those are are the methods that do the actual work. OFStream - * uses those for all other methods and does all the caching and other - * stuff for you. If you override these methods without the lowlevel - * prefix, you will break caching and get broken results! + * \note If you want to subclass this, override + * \ref lowlevelReadIntoBuffer:length:, \ref lowlevelWriteBuffer:length: + * and \ref lowlevelIsAtEndOfStream, but nothing else, as those are are + * the methods that do the actual work. OFStream uses those for all other + * methods and does all the caching and other stuff for you. If you + * override these methods without the lowlevel prefix, you will + * break caching and get broken results! */ @interface OFStream: OFObject { char *cache; char *writeBuffer; @@ -79,13 +80,13 @@ /** * \brief Reads at most size bytes from the stream into a buffer. * * On network streams, this might read less than the specified number of bytes. * If you want to read exactly the specified number of bytes, use - * -readIntoBuffer:exactLength:. Note that a read can even return 0 bytes - + * \ref readIntoBuffer:exactLength:. Note that a read can even return 0 bytes - * this does not necessarily mean that the stream ended, so you still need to - * check isAtEndOfStream. + * check \ref isAtEndOfStream. * * \param buffer The buffer into which the data is read * \param length The length of the data that should be read at most. * The buffer must be at least this big! * \return The number of bytes read @@ -95,13 +96,13 @@ /** * \brief Reads exactly the specified length bytes from the stream into a * buffer. * - * Unlike readIntoBuffer:length:, this method does not return when less than the - * specified length has been read - instead, it waits until it got exactly the - * specified length. + * Unlike \ref readIntoBuffer:length:, 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 @@ -115,13 +116,13 @@ * \brief Asyncronously reads at most size bytes from the stream into a * buffer. * * On network streams, this might read less than the specified number of bytes. * If you want to read exactly the specified number of bytes, use - * asyncReadIntoBuffer:exactLength:block:. Note that a read can even return 0 - * bytes - this does not necessarily mean that the stream ended, so you still - * need to check isAtEndOfStream. + * \ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even + * return 0 bytes - this does not necessarily mean that the stream ended, so + * you still need to check \ref isAtEndOfStream. * * \param buffer The buffer into which the data is read. * The buffer must not be free'd before the async read completed! * \param length The length of the data that should be read at most. * The buffer must be at least this big! @@ -142,11 +143,11 @@ /** * \brief Asyncronously reads exactly the specified length bytes from the * stream into a buffer. * - * Unlike asyncReadIntoBuffer:length:block, this method does not call the + * Unlike \ref asyncReadIntoBuffer:length:block, this method does not call the * method when less than the specified length has been read - instead, it waits * until it got exactly the specified length, the stream has ended or an * exception occurred. * * \param buffer The buffer into which the data is read @@ -172,13 +173,13 @@ * \brief Asyncronously reads at most size bytes from the stream into a * buffer. * * On network streams, this might read less than the specified number of bytes. * If you want to read exactly the specified number of bytes, use - * asyncReadIntoBuffer:exactLength:block:. Note that a read can even return 0 - * bytes - this does not necessarily mean that the stream ended, so you still - * need to check isAtEndOfStream. + * \ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even + * return 0 bytes - this does not necessarily mean that the stream ended, so + * you still need to check \ref isAtEndOfStream. * * \param buffer The buffer into which the data is read. * The buffer must not be free'd before the async read completed! * \param length The length of the data that should be read at most. * The buffer must be at least this big! @@ -194,11 +195,11 @@ /** * \brief Asyncronously reads exactly the specified length bytes from the * stream into a buffer. * - * Unlike asyncReadIntoBuffer:length:block, this method does not invoke the + * Unlike \ref asyncReadIntoBuffer:length:block, this method does not invoke the * block when less than the specified length has been read - instead, it waits * until it got exactly the specified length, the stream has ended or an * exception occurred. * * \param buffer The buffer into which the data is read @@ -630,12 +631,12 @@ */ - (OFString*)tryReadLine; /** * \brief Tries to read a line from the stream with the specified encoding (see - * readLineWithEncoding:) and returns nil if no complete line has been - * received yet. + * \ref readLineWithEncoding:) and returns nil if no complete line has + * been received yet. * * \param encoding The encoding used by the stream * \return The line that was read, autoreleased, or nil if the line is not * complete yet */ @@ -663,23 +664,23 @@ - (OFString*)readTillDelimiter: (OFString*)delimiter encoding: (of_string_encoding_t)encoding; /** * \brief Tries to reads until the specified string or \\0 is found or the end - * of stream (see readTillDelimiter:) and returns nil if not enough data - * has been received yet. + * of stream (see \ref readTillDelimiter:) and returns nil if not enough + * data has been received yet. * * \param delimiter The delimiter * \return The line that was read, autoreleased, or nil if the end of the * stream has been reached. */ - (OFString*)tryReadTillDelimiter: (OFString*)delimiter; /** * \brief Tries to read until the specified string or \\0 is found or the end - * of stream occurs (see readTIllDelimiterWithEncoding:) and returns nil - * if not enough data has been received yet. + * of stream occurs (see \ref readTillDelimiterWithEncoding:) and + * returns nil if not enough data has been received yet. * * \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. Index: src/OFStreamObserver.h ================================================================== --- src/OFStreamObserver.h +++ src/OFStreamObserver.h @@ -43,11 +43,11 @@ @optional #endif /** * \brief This callback is called when a stream did get ready for reading. * - * NOTE: When -[tryReadLine] or -[tryReadTillDelimiter:] has been called on the + * \note When \ref tryReadLine or \ref tryReadTillDelimiter: has been called on * the stream, this callback will not be called again until new data has * been received, even though there is still data in the cache. The reason * for this is to prevent spinning in a loop when there is an incomplete * string in the cache. Once the string is complete, the callback will be * called again if there is data in the cache. @@ -72,11 +72,11 @@ @end /** * \brief A class that can observe multiple streams at once. * - * Note: Currently, Win32 can only observe sockets and not files! + * \note Currently, Win32 can only observe sockets and not files! */ @interface OFStreamObserver: OFObject { OFMutableArray *readStreams; OFMutableArray *writeStreams; @@ -123,12 +123,12 @@ * 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. * - * 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. + * If there is an \ref observe call blocking, it will be canceled. The reason + * for this is to prevent blocking even though the new added stream is ready. * * \param stream The stream to observe for reading */ - (void)addStreamForReading: (OFStream*)stream; @@ -135,32 +135,32 @@ /** * \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. + * If there is an \ref observe call blocking, it will be canceled. The reason + * for this is to prevent blocking even though the new added stream is ready. * * \param stream The stream to observe for writing */ - (void)addStreamForWriting: (OFStream*)stream; /** * \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. + * If there is an \ref 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)removeStreamForReading: (OFStream*)stream; /** * \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. + * If there is an \ref 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)removeStreamForWriting: (OFStream*)stream; Index: src/OFString+JSONValue.h ================================================================== --- src/OFString+JSONValue.h +++ src/OFString+JSONValue.h @@ -36,11 +36,11 @@ * this is that most JSON parsers allow JSON data just consisting of a * single primitive, leading to realworld JSON files sometimes only * consisting of a single primitive. Therefore, you should not make any * assumptions about the object returned by this method if you don't * want your program to terminate due to a message not understood, but - * instead check the returned object using -[isKindOfClass:]. + * instead check the returned object using \ref isKindOfClass:. * * \return An object */ - (id)JSONValue; @end Index: src/OFString+XMLUnescaping.h ================================================================== --- src/OFString+XMLUnescaping.h +++ src/OFString+XMLUnescaping.h @@ -23,17 +23,17 @@ #ifdef __cplusplus } #endif #ifdef OF_HAVE_BLOCKS -typedef OFString* (^of_string_xml_unescaping_block_t)(OFString *str, +typedef OFString* (^of_string_xml_unescaping_block_t)(OFString *string, OFString *entity); #endif /** * \brief A protocol that needs to be implemented by delegates for - * -[stringByXMLUnescapingWithHandler:]. + * stringByXMLUnescapingWithHandler:. */ @protocol OFStringXMLUnescapingDelegate /** * \brief This callback is called when an unknown entity was found while trying * to unescape XML. @@ -40,15 +40,15 @@ * * 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 string 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 */ -- (OFString*)string: (OFString*)str +- (OFString*)string: (OFString*)string containsUnknownEntityNamed: (OFString*)entity; @end /** * \brief A category for unescaping XML in strings. Index: src/OFString.h ================================================================== --- src/OFString.h +++ src/OFString.h @@ -73,16 +73,10 @@ @class OFArray; @class OFURL; /** * \brief A class for handling strings. - * - * Warning: If you add methods to OFString using a category, you are not - * allowed to access the ivars directly, as these might be still uninitialized - * for a constant string and get initialized on the first message! Therefore, - * you should use the corresponding methods to get the ivars, which ensures the - * constant string is initialized. */ @interface OFString: OFObject #ifdef OF_HAVE_PROPERTIES @property (readonly) size_t length; @@ -626,11 +620,12 @@ /** * \brief Returns the range of the string. * * \param string The string to search * \param options Options modifying search behaviour. - * Possible values: OF_STRING_SEARCH_BACKWARDS + * Possible values: + * * OF_STRING_SEARCH_BACKWARDS * \return The range of the first occurrence of the string or a range with * OF_NOT_FOUND as start position if it was not found */ - (of_range_t)rangeOfString: (OFString*)string options: (int)options; @@ -638,11 +633,12 @@ /** * \brief Returns the range of the string in the specified range. * * \param string The string to search * \param options Options modifying search behaviour. - * Possible values: OF_STRING_SEARCH_BACKWARDS + * Possible values: + * * OF_STRING_SEARCH_BACKWARDS * \param range The range in which to search * \return The range of the first occurrence of the string or a range with * OF_NOT_FOUND as start position if it was not found */ - (of_range_t)rangeOfString: (OFString*)string @@ -705,11 +701,12 @@ * string in the specified range with the specified replacement. * * \param string The string to replace * \param replacement The string with which it should be replaced * \param options Options modifying search behaviour. - * Possible values: None yet + * Possible values: + * * None yet * \param range The range in which to replace the string * \return A new string with the occurrences of the specified string replaced */ - (OFString*)stringByReplacingOccurrencesOfString: (OFString*)string withString: (OFString*)replacement @@ -731,11 +728,11 @@ - (OFString*)lowercaseString; /** * \brief Returns the string capitalized. * - * \note This only considers spaces, tab and newlines to be word delimiters! + * \note This only considers spaces, tabs and newlines to be word delimiters! * Also note that this might change in the future to all word delimiters * specified by Unicode! * * \return The capitalized string */ @@ -789,12 +786,13 @@ /** * \brief Separates an OFString into an OFArray of OFStrings. * * \param delimiter The delimiter for separating - * \param options Options according to which the string should be separated - * Possible values: OF_STRING_SKIP_EMPTY + * \param options Options according to which the string should be separated. + * Possible values: + * * OF_STRING_SKIP_EMPTY * \return An autoreleased OFArray with the separated string */ - (OFArray*)componentsSeparatedByString: (OFString*)delimiter options: (int)options; Index: src/OFThreadPool.h ================================================================== --- src/OFThreadPool.h +++ src/OFThreadPool.h @@ -62,22 +62,10 @@ * \param size The number of threads for the pool * \return A new thread pool with the specified number of threads */ + (instancetype)threadPoolWithSize: (size_t)size; -/** - * \brief Initializes an already allocated OFThreadPool with one thread for - * each core in the system. - * - * \warning If for some reason the number of cores in the system could not be - * determined, the pool will only have one thread! - * - * \return An initialized OFThreadPool with one thread for each core in the - * system - */ -- init; - /** * \brief Initializes an already allocated OFThreadPool with the specified * number of threads. * * \warning If for some reason the number of cores in the system could not be