Index: src/OFArray.h ================================================================== --- src/OFArray.h +++ src/OFArray.h @@ -138,17 +138,17 @@ */ - initWithObjects: (id const*)objects count: (size_t)count; /*! - * @brief Returns a specified object of the array. + * @brief Returns the object at the specified index in the array. * - * The returned object is not retained and autoreleased for performance - * reasons! + * @warning The returned object is *not* retained and autoreleased for + * performance reasons! * - * @param index The number of the object to return - * @return The specified object of the OFArray + * @param index The index of the object to return + * @return The object at the specified index in the array */ - (id)objectAtIndex: (size_t)index; - (id)objectAtIndexedSubscript: (size_t)index; /*! @@ -198,22 +198,22 @@ - (BOOL)containsObjectIdenticalTo: (id)object; /*! * @brief Returns the first object of the array or nil. * - * The returned object is not retained and autoreleased for performance - * reasons! + * @warning The returned object is *not* retained and autoreleased for + * performance reasons! * * @return The first object of the array or nil */ - (id)firstObject; /*! * @brief Returns the last object of the array or nil. * - * The returned object is not retained and autoreleased for performance - * reasons! + * @warning The returned object is *not* retained and autoreleased for + * performance reasons! * * @return The last object of the array or nil */ - (id)lastObject; Index: src/OFDictionary.h ================================================================== --- src/OFDictionary.h +++ src/OFDictionary.h @@ -168,12 +168,12 @@ arguments: (va_list)arguments; /*! * @brief Returns the object for the given key or nil if the key was not found. * - * The returned object is not retained and autoreleased for performance - * reasons! + * @warning The returned object is *not* retained and autoreleased for + * performance reasons! * * @param key The key whose object should be returned * @return The object for the given key or nil if the key was not found */ - (id)objectForKey: (id)key; Index: src/OFList.h ================================================================== --- src/OFList.h +++ src/OFList.h @@ -135,22 +135,22 @@ - (BOOL)containsObjectIdenticalTo: (id)object; /*! * @brief Returns the first object of the list or nil. * - * The returned object is not retained and autoreleased for performance - * reasons! + * @warning The returned object is *not* retained and autoreleased for + * performance reasons! * * @return The first object of the list or nil */ - (id)firstObject; /*! * @brief Returns the last object of the list or nil. * - * The returned object is not retained and autoreleased for performance - * reasons! + * @warning The returned object is *not* retained and autoreleased for + * performance reasons! * * @return The last object of the list or nil */ - (id)lastObject; Index: src/OFSeekableStream.h ================================================================== --- src/OFSeekableStream.h +++ src/OFSeekableStream.h @@ -29,12 +29,12 @@ * @brief A stream that supports seeking. * * @note If you want to subclass this, override * @ref lowlevelSeekToOffset:whence:. OFSeekableStream uses this method * and makes it work together with the caching of OFStream. If you - * override this methods without the lowlevel prefix, you will - * break caching, get broken results and seek to the wrong position! + * override this 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 @@ -38,24 +38,24 @@ #endif /*! * @brief A base class for different types of streams. * - * @warning Even though the OFCopying protocol is implemented, it does - * not return an independent copy of the stream, but instead - * retains it. This is so that the stream can be used as a key for a - * dictionary, so context can be associated with a stream. Using a - * stream in more than one thread at the same time is not thread-safe, - * even if copy was called to create one "instance" for every thread! + * @warning Even though the OFCopying protocol is implemented, it does *not* + * return an independent copy of the stream, but instead retains it. + * This is so that the stream can be used as a key for a dictionary, + * so context can be associated with a stream. Using a stream in more + * than one thread at the same time is not thread-safe, even if copy + * was called to create one "instance" for every thread! * * @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! + * override these methods without the lowlevel prefix, you *will* break + * caching and get broken results! */ @interface OFStream: OFObject { char *cache; char *writeBuffer; @@ -76,21 +76,21 @@ * @return A boolean whether the end of the stream has been reached */ - (BOOL)isAtEndOfStream; /*! - * @brief Reads at most size bytes from the stream into a buffer. + * @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 * @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 @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! + * The buffer *must* be *at least* this big! * @return The number of bytes read */ - (size_t)readIntoBuffer: (void*)buffer length: (size_t)length; @@ -105,17 +105,17 @@ * @warning Only call this when you know that specified amount of data is * available! Otherwise you will get an exception! * * @param buffer The buffer into which the data is read * @param length The length of the data that should be read. - * The buffer must be exactly this big! + * The buffer *must* be *at least* this big! */ - (void)readIntoBuffer: (void*)buffer exactLength: (size_t)length; /*! - * @brief Asyncronously reads at most size bytes from the stream into a + * @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 * @ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even @@ -123,11 +123,11 @@ * 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! + * The buffer *must* be *at least* this big! * @param target The target on which the selector should be called when the * data has been received. If the method returns YES, it will be * called again with the same buffer and maximum length when more * data has been received. If you want the next method in the * queue to handle the data received next, you need to return NO @@ -150,11 +150,11 @@ * 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 * @param length The length of the data that should be read. - * The buffer must be exactly this big! + * The buffer *must* be *at least* this big! * @param target The target on which the selector should be called when the * data has been received. If the method returns YES, it will be * called again with the same buffer and exact length when more * data has been received. If you want the next method in the * queue to handle the data received next, you need to return NO @@ -168,11 +168,11 @@ target: (id)target selector: (SEL)selector; #ifdef OF_HAVE_BLOCKS /*! - * @brief Asyncronously reads at most size bytes from the stream into a + * @brief Asyncronously reads *at most* ref 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 * @ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even @@ -180,11 +180,11 @@ * 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! + * The buffer *must* be *at least* this big! * @param block The block to call when the data has been received. * If the block returns YES, it will be called again with the same * buffer and maximum length when more data has been received. If * you want the next block in the queue to handle the data * received next, you need to return NO from the block. @@ -202,11 +202,11 @@ * 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 * @param length The length of the data that should be read. - * The buffer must be exactly this big! + * The buffer *must* be *at least* this big! * @param block The block to call when the data has been received. * If the block returns YES, it will be called again with the same * buffer and exact length when more data has been received. If * you want the next block in the queue to handle the data * received next, you need to return NO from the block. Index: src/OFThread.h ================================================================== --- src/OFThread.h +++ src/OFThread.h @@ -36,14 +36,14 @@ * @brief A class which provides portable threads. * * To use it, you should create a new class derived from it and reimplement * main. * - * @warning Even though the OFCopying protocol is implemented, it does - * not return an independent copy of the thread, but instead - * retains it. This is so that the thread can be used as a key for a - * dictionary, so context can be associated with a thread. + * @warning Even though the OFCopying protocol is implemented, it does *not* + * return an independent copy of the thread, but instead retains it. + * This is so that the thread can be used as a key for a dictionary, + * so context can be associated with a thread. */ @interface OFThread: OFObject { #ifdef OF_THREAD_M @public @@ -102,12 +102,12 @@ forTLSKey: (OFTLSKey*)key; /*! * @brief Returns the object for the specified Thread Local Storage key. * - * The returned object is not retained and autoreleased for performance - * reasons! + * @warning The returned object is *not* retained and autoreleased for + * performance reasons! * * @param key The Thread Local Storage key */ + (id)objectForTLSKey: (OFTLSKey*)key; Index: src/exceptions/OFAllocFailedException.h ================================================================== --- src/exceptions/OFAllocFailedException.h +++ src/exceptions/OFAllocFailedException.h @@ -23,18 +23,18 @@ * * This exception is preallocated, as when there's no memory, no exception can * be allocated of course. That's why you shouldn't and even can't deallocate * it. * - * This is the only exception that is not an OFException as it's special. - * It does not know for which class allocation failed and it should not be - * handled like other exceptions, as the exception handling code is not - * allowed to allocate any memory. + * This is the only exception which is not an OFException as it's special. It + * does not know for which class allocation failed and it should not be handled + * like other exceptions, as the exception handling code is not allowed to + * allocate *any* memory. */ @interface OFAllocFailedException: OFObject /*! * @brief Returns a description of the exception. * * @return A description of the exception */ - (OFString*)description; @end