Index: src/OFKeyValueCoding.h ================================================================== --- src/OFKeyValueCoding.h +++ src/OFKeyValueCoding.h @@ -31,18 +31,22 @@ /** * @brief Returns the value for the specified key. * * @param key The key of the value to return * @return The value for the specified key + * @throw OFUndefinedKeyException The specified key does not exist and + * @ref valueForUndefinedKey: was not overridden */ - (nullable id)valueForKey: (OFString *)key; /** * @brief Returns the value for the specified key path. * * @param keyPath The key path of the value to return * @return The value for the specified key path + * @throw OFUndefinedKeyException The specified key does not exist and + * @ref valueForUndefinedKey: was not overridden */ - (nullable id)valueForKeyPath: (OFString *)keyPath; /** * @brief This is called by @ref valueForKey: if the specified key does not @@ -50,26 +54,33 @@ * * By default, this throws an @ref OFUndefinedKeyException. * * @param key The undefined key of the value to return * @return The value for the specified undefined key + * @throw OFUndefinedKeyException The specified key does not exist */ - (nullable id)valueForUndefinedKey: (OFString *)key; /** * @brief Set the value for the specified key. * * @param value The value for the specified key * @param key The key of the value to set + * @throw OFUndefinedKeyException The specified key does not exist and + * @ref setValue:forUndefinedKey: was not + * overridden */ - (void)setValue: (nullable id)value forKey: (OFString *)key; /** * @brief Set the value for the specified key path. * * @param value The value for the specified key path * @param keyPath The key path of the value to set + * @throw OFUndefinedKeyException The specified key does not exist and + * @ref setValue:forUndefinedKey: was not + * overridden */ - (void)setValue: (nullable id)value forKeyPath: (OFString *)keyPath; /** * @brief This is called by @ref setValue:forKey: if the specified key does not @@ -77,10 +88,11 @@ * * By default, this throws an @ref OFUndefinedKeyException. * * @param value The value for the specified undefined key * @param key The undefined key of the value to set + * @throw OFUndefinedKeyException The specified key does not exist */ - (void)setValue: (nullable id)value forUndefinedKey: (OFString *)key; /** * @brief This is called by @ref setValue:forKey: if the specified key is a Index: src/OFLocking.h ================================================================== --- src/OFLocking.h +++ src/OFLocking.h @@ -28,22 +28,29 @@ */ @property OF_NULLABLE_PROPERTY (copy, nonatomic) OFString *name; /** * @brief Locks the lock. + * + * @throw OFLockFailedException Acquiring the lock failed */ - (void)lock; /** * @brief Tries to lock the lock. * * @return A boolean whether the lock could be locked + * + * @throw OFLockFailedException The lock could not be acquired for another + * reason than it already being held */ - (bool)tryLock; /** * @brief Unlocks the lock. + * + * @throw OFUnlockFailedException Releasing the lock failed */ - (void)unlock; @end OF_ASSUME_NONNULL_END Index: src/OFMutex.h ================================================================== --- src/OFMutex.h +++ src/OFMutex.h @@ -21,10 +21,15 @@ /** * @class OFMutex OFMutex.h ObjFW/OFMutex.h * * @brief A class for creating mutual exclusions. + * + * If the mutex is deallocated while being held, it throws an + * @ref OFStillLockedException. While this might break ARC's assumption that no + * object ever throws in dealloc, it is considered a fatal programmer error + * that should terminate the application. */ @interface OFMutex: OFObject { OFPlainMutex _mutex; bool _initialized; Index: src/OFPlugin.h ================================================================== --- src/OFPlugin.h +++ src/OFPlugin.h @@ -54,10 +54,11 @@ * @brief Creates a new OFPlugin by loading the plugin with the specified path. * * @param path The path to the plugin file. The suffix is appended * automatically. * @return An new, autoreleased OFPlugin + * @throw OFLoadPluginFailedException The plugin could not be loaded */ + (instancetype)pluginWithPath: (OFString *)path; /** * @brief Initializes an already allocated OFPlugin by loading the plugin with @@ -64,10 +65,11 @@ * the specified path. * * @param path The path to the plugin file. The suffix is appended * automatically. * @return An initialized OFPlugin + * @throw OFLoadPluginFailedException The plugin could not be loaded */ - (instancetype)initWithPath: (OFString *)path; /** * @brief Returns the address for the specified symbol, or `nil` if not found. Index: src/OFRecursiveMutex.h ================================================================== --- src/OFRecursiveMutex.h +++ src/OFRecursiveMutex.h @@ -22,10 +22,15 @@ /** * @class OFRecursiveMutex OFRecursiveMutex.h ObjFW/OFRecursiveMutex.h * * @brief A class for creating mutual exclusions which can be entered * recursively. + * + * If the mutex is deallocated while being held, it throws an + * @ref OFStillLockedException. While this might break ARC's assumption that no + * object ever throws in dealloc, it is considered a fatal programmer error + * that should terminate the application. */ OF_SUBCLASSING_RESTRICTED @interface OFRecursiveMutex: OFObject { OFPlainRecursiveMutex _rmutex;