Index: src/OFCryptographicHash.h ================================================================== --- src/OFCryptographicHash.h +++ src/OFCryptographicHash.h @@ -56,10 +56,12 @@ /** * @brief A buffer containing the cryptographic hash. * * The size of the buffer depends on the hash used. The buffer is part of the * receiver's memory pool. + * + * @throw OFHashNotCalculatedException The hash hasn't been calculated yet */ @property (readonly, nonatomic) const unsigned char *digest OF_RETURNS_INNER_POINTER; /** @@ -95,15 +97,18 @@ /** * @brief Adds a buffer to the cryptographic hash to be calculated. * * @param buffer The buffer which should be included into the calculation * @param length The length of the buffer + * @throw OFHashAlreadyCalculatedException The hash has already been calculated */ - (void)updateWithBuffer: (const void *)buffer length: (size_t)length; /** * @brief Performs the final calculation of the cryptographic hash. + * + * @throw OFHashAlreadyCalculatedException The hash has already been calculated */ - (void)calculate; /** * @brief Resets all state so that a new hash can be calculated. Index: src/OFEnumerator.h ================================================================== --- src/OFEnumerator.h +++ src/OFEnumerator.h @@ -80,10 +80,12 @@ * @param state Context information for the enumeration * @param objects A pointer to an array where to put the objects * @param count The number of objects that can be stored at objects * @return The number of objects returned in objects or 0 when the enumeration * finished. + * @throw OFEnumerationMutationException The object was mutated during + * enumeration */ - (int)countByEnumeratingWithState: (OFFastEnumerationState *)state objects: (id __unsafe_unretained _Nonnull *_Nonnull) objects count: (int)count; @@ -100,20 +102,24 @@ #endif /** * @brief Returns the next object or `nil` if there is none left. * * @return The next object or `nil` if there is none left + * @throw OFEnumerationMutationException The object was mutated during + * enumeration */ - (nullable ObjectType)nextObject; /** * @brief Returns an array of all remaining objects in the collection. * * @return An array of all remaining objects in the collection. + * @throw OFEnumerationMutationException The object was mutated during + * enumeration */ - (OFArray OF_GENERIC(ObjectType) *)allObjects; #if !defined(OF_HAVE_GENERICS) && !defined(DOXYGEN) # undef ObjectType #endif @end OF_ASSUME_NONNULL_END Index: src/OFHTTPCookie.h ================================================================== --- src/OFHTTPCookie.h +++ src/OFHTTPCookie.h @@ -84,10 +84,12 @@ * returns an array of cookies. * * @param headerFields The response header fields to parse * @param URL The URL for the response header fields to parse * @return An array of cookies + * @throw OFInvalidFormatException The specified response header has an invalid + * format */ + (OFArray OF_GENERIC(OFHTTPCookie *) *)cookiesWithResponseHeaderFields: (OFDictionary OF_GENERIC(OFString *, OFString *) *)headerFields forURL: (OFURL *)URL; Index: src/OFHTTPRequest.h ================================================================== --- src/OFHTTPRequest.h +++ src/OFHTTPRequest.h @@ -81,15 +81,23 @@ */ @property (copy, nonatomic) OFURL *URL; /** * @brief The protocol version of the HTTP request. + * + * @throw OFUnsupportedVersionException The specified version cannot be set + * because it is not supported */ @property (nonatomic) OFHTTPRequestProtocolVersion protocolVersion; /** * @brief The protocol version of the HTTP request as a string. + * + * @throw OFUnsupportedVersionException The specified version cannot be set + * because it is not supported + * @throw OFInvalidFormatException The specified version cannot be set because + * it is not in a valid format */ @property (copy, nonatomic) OFString *protocolVersionString; /** * @brief The request method of the HTTP request. @@ -143,12 +151,14 @@ /** * @brief Returns the request method for the specified string. * * @param string The string for which the request method should be returned * @return The request method for the specified string + * @throw OFInvalidFormatException The specified string is not a valid HTTP + * request method */ extern OFHTTPRequestMethod OFHTTPRequestMethodParseName(OFString *string); #ifdef __cplusplus } #endif OF_ASSUME_NONNULL_END Index: src/OFHTTPRequest.m ================================================================== --- src/OFHTTPRequest.m +++ src/OFHTTPRequest.m @@ -72,11 +72,11 @@ if ([string isEqual: @"TRACE"]) return OFHTTPRequestMethodTrace; if ([string isEqual: @"CONNECT"]) return OFHTTPRequestMethodConnect; - @throw [OFInvalidArgumentException exception]; + @throw [OFInvalidFormatException exception]; } @implementation OFHTTPRequest @synthesize URL = _URL, method = _method, headers = _headers; Index: src/OFHTTPResponse.h ================================================================== --- src/OFHTTPResponse.h +++ src/OFHTTPResponse.h @@ -36,15 +36,23 @@ OFDictionary OF_GENERIC(OFString *, OFString *) *_headers; } /** * @brief The protocol version of the HTTP request response. + * + * @throw OFUnsupportedVersionException The specified version cannot be set + * because it is not supported */ @property (nonatomic) OFHTTPRequestProtocolVersion protocolVersion; /** * @brief The protocol version of the HTTP request response as a string. + * + * @throw OFUnsupportedVersionException The specified version cannot be set + * because it is not supported + * @throw OFInvalidFormatException The specified version cannot be set because + * it is not in a valid format */ @property (copy, nonatomic) OFString *protocolVersionString; /** * @brief The status code of the response to the HTTP request. Index: src/OFHTTPServer.h ================================================================== --- src/OFHTTPServer.h +++ src/OFHTTPServer.h @@ -104,20 +104,20 @@ } /** * @brief The host on which the HTTP server will listen. * - * Setting this after @ref start has been called raises an - * @ref OFAlreadyConnectedException. + * @throw OFAlreadyConnectedException The host could not be set because + * @ref start had already been called */ @property OF_NULLABLE_PROPERTY (copy, nonatomic) OFString *host; /** * @brief The port on which the HTTP server will listen. * - * Setting this after @ref start has been called raises an - * @ref OFAlreadyConnectedException. + * @throw OFAlreadyConnectedException The port could not be set because + * @ref start had already been called */ @property (nonatomic) uint16_t port; /** * @brief The delegate for the HTTP server. @@ -132,12 +132,12 @@ * If this is larger than 1 (the default), one thread will be used to accept * incoming connections and all others will be used to handle connections. * * For maximum CPU utilization, set this to `[OFSystemInfo numberOfCPUs] + 1`. * - * Setting this after @ref start has been called raises an - * @ref OFAlreadyConnectedException. + * @throw OFAlreadyConnectedException The number of threads could not be set + * because @ref start had already been called */ @property (nonatomic) size_t numberOfThreads; #endif /** @@ -155,10 +155,12 @@ */ + (instancetype)server; /** * @brief Starts the HTTP server in the current thread's run loop. + * + * @throw OFAlreadyConnectedException The server had already been started */ - (void)start; /** * @brief Stops the HTTP server, meaning it will not accept any new incoming Index: src/OFINICategory.h ================================================================== --- src/OFINICategory.h +++ src/OFINICategory.h @@ -76,10 +76,12 @@ * * @param key The key for which the long long should be returned * @param defaultValue The value to return if the key does not exist * @return The long long for the specified key or the specified default value * if it does not exist + * @throw OFInvalidFormatException The specified key is not in the correct + * format for a long long */ - (long long)longLongForKey: (OFString *)key defaultValue: (long long)defaultValue; /** @@ -91,10 +93,12 @@ * * @param key The key for which the bool should be returned * @param defaultValue The value to return if the key does not exist * @return The bool for the specified key or the specified default value if it * does not exist + * @throw OFInvalidFormatException The specified key is not in the correct + * format for a bool */ - (bool)boolForKey: (OFString *)key defaultValue: (bool)defaultValue; /** * @brief Returns the float for the specified key or the specified default @@ -105,10 +109,12 @@ * * @param key The key for which the float should be returned * @param defaultValue The value to return if the key does not exist * @return The float for the specified key or the specified default value if it * does not exist + * @throw OFInvalidFormatException The specified key is not in the correct + * format for a float */ - (float)floatForKey: (OFString *)key defaultValue: (float)defaultValue; /** * @brief Returns the double for the specified key or the specified default @@ -119,10 +125,12 @@ * * @param key The key for which the double should be returned * @param defaultValue The value to return if the key does not exist * @return The double for the specified key or the specified default value if * it does not exist + * @throw OFInvalidFormatException The specified key is not in the correct + * format for a double */ - (double)doubleForKey: (OFString *)key defaultValue: (double)defaultValue; /** * @brief Returns an array of strings for the specified multi-key, or an empty Index: src/OFINIFile.h ================================================================== --- src/OFINIFile.h +++ src/OFINIFile.h @@ -42,21 +42,28 @@ * @brief Creates a new OFINIFile with the contents of the specified file. * * @param URL The URL to the file whose contents the OFINIFile should contain * * @return A new, autoreleased OFINIFile with the contents of the specified file + * @throw OFInvalidFormatException The format of the specified INI file is + * invalid + * @throw OFInvalidEncodingException The INI file is not in the specified + * encoding */ + (instancetype)fileWithURL: (OFURL *)URL; /** * @brief Creates a new OFINIFile with the contents of the specified file in * the specified encoding. * * @param URL The URL to the file whose contents the OFINIFile should contain * @param encoding The encoding of the specified file - * * @return A new, autoreleased OFINIFile with the contents of the specified file + * @throw OFInvalidFormatException The format of the specified INI file is + * invalid + * @throw OFInvalidEncodingException The INI file is not in the specified + * encoding */ + (instancetype)fileWithURL: (OFURL *)URL encoding: (OFStringEncoding)encoding; - (instancetype)init OF_UNAVAILABLE; @@ -65,21 +72,28 @@ * specified file. * * @param URL The URL to the file whose contents the OFINIFile should contain * * @return An initialized OFINIFile with the contents of the specified file + * @throw OFInvalidFormatException The format of the specified INI file is + * invalid + * @throw OFInvalidEncodingException The INI file is not in the specified + * encoding */ - (instancetype)initWithURL: (OFURL *)URL; /** * @brief Initializes an already allocated OFINIFile with the contents of the * specified file in the specified encoding. * * @param URL The URL to the file whose contents the OFINIFile should contain * @param encoding The encoding of the specified file - * * @return An initialized OFINIFile with the contents of the specified file + * @throw OFInvalidFormatException The format of the specified INI file is + * invalid + * @throw OFInvalidEncodingException The INI file is not in the specified + * encoding */ - (instancetype)initWithURL: (OFURL *)URL encoding: (OFStringEncoding)encoding OF_DESIGNATED_INITIALIZER; Index: src/OFIPXSocket.h ================================================================== --- src/OFIPXSocket.h +++ src/OFIPXSocket.h @@ -69,10 +69,12 @@ * * @param port The port (sometimes called socket number) to bind to. 0 means to * pick one and return it. * @param packetType The packet type to use on the socket * @return The address on which this socket can be reached + * @throw OFBindFailedException Binding failed + * @throw OFAlreadyConnectedException The socket is already bound */ - (OFSocketAddress)bindToPort: (uint16_t)port packetType: (uint8_t)packetType; @end OF_ASSUME_NONNULL_END Index: src/OFKernelEventObserver.h ================================================================== --- src/OFKernelEventObserver.h +++ src/OFKernelEventObserver.h @@ -210,29 +210,32 @@ - (void)removeObjectForWriting: (id )object; /** * @brief Observes all objects and blocks until an event happens on an object. * - * @throw OFObserveKernelEventsFailedException Observing for kernel events failed + * @throw OFObserveKernelEventsFailedException Observing for kernel events + * failed */ - (void)observe; /** * @brief Observes all objects until an event happens on an object or the * timeout is reached. * * @param timeInterval The time to wait for an event, in seconds - * @throw OFObserveKernelEventsFailedException Observing for kernel events failed + * @throw OFObserveKernelEventsFailedException Observing for kernel events + * failed */ - (void)observeForTimeInterval: (OFTimeInterval)timeInterval; /** * @brief Observes all objects until an event happens on an object or the * specified date is reached. * * @param date The until which to observe - * @throw OFObserveKernelEventsFailedException Observing for kernel events failed + * @throw OFObserveKernelEventsFailedException Observing for kernel events + * failed */ - (void)observeUntilDate: (OFDate *)date; /** * @brief Cancels the currently blocking observe call. Index: src/OFLHAArchive.h ================================================================== --- src/OFLHAArchive.h +++ src/OFLHAArchive.h @@ -115,10 +115,14 @@ * invalidated stream will throw an @ref OFReadFailedException or * @ref OFWriteFailedException! * * @return The next entry from the LHA archive or `nil` if all entries have * been read + * @throw OFInvalidFormatException The archive's format is invalid + * @throw OFUnsupportedVersionException The archive's format is of an + * unsupported version + * @throw OFTruncatedDataException The archive was truncated */ - (nullable OFLHAArchiveEntry *)nextEntry; /** * @brief Returns a stream for writing the specified entry. Index: src/OFLocale.h ================================================================== --- src/OFLocale.h +++ src/OFLocale.h @@ -26,10 +26,12 @@ * @brief Returns the localized string for the specified ID with the specified * arguments inserted. * * @param ID The ID of the localized string to retrieve * @return The localized string with the specified arguments replaced + * @throw OFInvalidFormatException The string (either the fallback or the + * localized one) contains an invalid format */ #define OF_LOCALIZED(ID, ...) \ [[OFLocale currentLocale] localizedStringForID: ID \ fallback: __VA_ARGS__, nil] @@ -207,12 +209,14 @@ * plural scripting, just like with the JSON language files. * @param arguments A va_list of arguments, consisting of pairs of variable * names and values to replace in the localized string, * terminated with `nil` * @return The localized string + * @throw OFInvalidFormatException The string (either the fallback or the + * localized one) contains an invalid format */ - (OFString *)localizedStringForID: (OFConstantString *)ID fallback: (id)fallback arguments: (va_list)arguments; @end OF_ASSUME_NONNULL_END