Index: src/OFEnumerator.h ================================================================== --- src/OFEnumerator.h +++ src/OFEnumerator.h @@ -62,9 +62,19 @@ * * The OFFastEnumeration protocol needs to be implemented by all classes * supporting fast enumeration. */ @protocol OFFastEnumeration +/** + * \brief A method which is called by the code produced by the compiler when + * doing a fast enumeration. + * + * \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. + */ - (int)countByEnumeratingWithState: (of_fast_enumeration_state_t*)state objects: (id*)objects count: (int)count; @end Index: src/OFFile.h ================================================================== --- src/OFFile.h +++ src/OFFile.h @@ -38,69 +38,83 @@ BOOL closable; BOOL isAtEndOfStream; } /** + * \brief Creates a new OFFile with the specified path and mode. + * * \param path The path to the file to open as a string * \param mode The mode in which the file should be opened as a string * \return A new autoreleased OFFile */ + fileWithPath: (OFString*)path mode: (OFString*)mode; /** + * \brief Creates a new OFFile with the specified file descriptor. + * * \param fileDescriptor A file descriptor, returned from for example open(). * It is not closed when the OFFile object is deallocated! * \return A new autoreleased OFFile */ + fileWithFileDescriptor: (int)fileDescriptor; /** + * \brief Returns the path fo the current working directory. + * * \return The path of the current working directory */ + (OFString*)currentDirectoryPath; /** + * \brief Checks whether a file exists at the specified path. + * * \param path The path to check * \return A boolean whether there is a file at the specified path */ + (BOOL)fileExistsAtPath: (OFString*)path; /** + * \brief Checks whether a directory exists at the specified path. + * * \param path The path to check * \return A boolean whether there is a directory at the specified path */ + (BOOL)directoryExistsAtPath: (OFString*)path; /** - * Creates a directory at the specified path. + * \brief Creates a directory at the specified path. * * \param path The path of the directory */ + (void)createDirectoryAtPath: (OFString*)path; /** + * \brief Returns an array with the files in the specified directory. + * * \param path The path of the directory * \return An array of OFStrings with the files at the specified path */ + (OFArray*)filesInDirectoryAtPath: (OFString*)path; /** - * Changes the current working directory. + * \brief Changes the current working directory. * * \param path The new directory to change to */ + (void)changeToDirectory: (OFString*)path; /** + * \brief Returns the date of the last modification of the file. + * * \return The date of the last modification of the file */ + (OFDate*)modificationDateOfFile: (OFString*)path; #ifndef _PSP /** - * Changes the mode of a file. + * \brief Changes the mode of a file. * * Only changes read-only flag on Windows. * * \param path The path to the file of which the mode should be changed as a * string @@ -110,11 +124,11 @@ toMode: (mode_t)mode; #endif #if !defined(_WIN32) && !defined(_PSP) /** - * Changes the owner of a file. + * \brief Changes the owner of a file. * * Not available on Windows. * * \param path The path to the file of which the owner should be changed as a * string @@ -125,44 +139,44 @@ toOwner: (OFString*)owner group: (OFString*)group; #endif /** - * Copies a file. + * \brief Copies a file. * * \param source The file to copy * \param destination The destination path */ + (void)copyFileAtPath: (OFString*)source toPath: (OFString*)destination; /** - * Renames a file. + * \brief Renames a file. * * \param source The file to rename * \param destination The new name */ + (void)renameFileAtPath: (OFString*)source toPath: (OFString*)destination; /** - * Deletes a file. + * \brief Deletes a file. * * \param path The path to the file of which should be deleted as a string */ + (void)deleteFileAtPath: (OFString*)path; /** - * Deletes an empty directory. + * \brief Deletes an empty directory. * * \param path The path to the directory which should be deleted as a string */ + (void)deleteDirectoryAtPath: (OFString*)path; #ifndef _WIN32 /** - * Hardlinks a file. + * \brief Creates a hard link for a file. * * Not available on Windows. * * \param source The path to the file of which should be linked as a string * \param destination The path to where the file should be linked as a string @@ -171,11 +185,11 @@ toPath: (OFString*)destination; #endif #if !defined(_WIN32) && !defined(_PSP) /** - * Symlinks a file. + * \brief Creates a symbolink link for a file. * * Not available on Windows. * * \param source The path to the file of which should be symlinked as a string * \param destination The path to where the file should be symlinked as a string @@ -183,21 +197,21 @@ + (void)symlinkFileAtPath: (OFString*)source toPath: (OFString*)destination; #endif /** - * Initializes an already allocated OFFile. + * \brief Initializes an already allocated OFFile. * * \param path The path to the file to open as a string * \param mode The mode in which the file should be opened as a string * \return An initialized OFFile */ - initWithPath: (OFString*)path mode: (OFString*)mode; /** - * Initializes an already allocated OFFile. + * \brief Initializes an already allocated OFFile. * * \param fileDescriptor A file descriptor, returned from for example open(). * It is not closed when the OFFile object is deallocated! */ - initWithFileDescriptor: (int)fileDescriptor; Index: src/OFHTTPRequest.h ================================================================== --- src/OFHTTPRequest.h +++ src/OFHTTPRequest.h @@ -39,11 +39,11 @@ #endif #ifdef OF_HAVE_OPTIONAL_PROTOCOLS @optional #endif /** - * This callback is called when the OFHTTPRequest received the headers. + * \brief A callback which is called when an OFHTTPRequest received headers. * * \param request The OFHTTPRequest which received the headers * \param headers The headers received * \param statusCode The status code received */ @@ -50,11 +50,11 @@ - (void)request: (OFHTTPRequest*)request didReceiveHeaders: (OFDictionary*)headers withStatusCode: (int)statusCode; /** - * This callback is called when the OFHTTPRequest received data. + * \brief A callback which is called when an OFHTTPRequest received data. * * This is useful for example if you want to update a status display. * * \param request The OFHTTPRequest which received data * \param data The data the OFHTTPRequest received @@ -63,11 +63,12 @@ - (void)request: (OFHTTPRequest*)request didReceiveData: (const char*)data withLength: (size_t)length; /** - * This callback is called when the OFHTTPRequest will follow a redirect. + * \brief A callback which is called when an OFHTTPRequest will follow a + * redirect. * * If you want to get the headers and data for each redirect, set the number of * redirects to 0 and perform a new OFHTTPRequest for each redirect. However, * this callback will not be called then and you have to look at the status code * to detect a redirect. @@ -107,124 +108,142 @@ @property (retain) id delegate; @property (assign) BOOL storesData; #endif /** + * \brief Creates a new OFHTTPRequest. + * * \return A new, autoreleased OFHTTPRequest */ + request; /** + * \brief Creates a new OFHTTPRequest with the specified URL. + * * \param URL The URL for the request * \return A new, autoreleased OFHTTPRequest */ + requestWithURL: (OFURL*)URL; /** - * Initializes an already allocated OFHTTPRequest with the specified URL. + * \brief Initializes an already allocated OFHTTPRequest with the specified URL. * * \param URL The URL for the request * \return An initialized OFHTTPRequest */ - initWithURL: (OFURL*)URL; /** - * Sets the URL for the HTTP request. + * \brief Sets the URL of the HTTP request. * - * \param URL The URL for the HTTP request + * \param URL The URL of the HTTP request */ - (void)setURL: (OFURL*)URL; /** - * \return The URL for the HTTP request + * \brief Returns the URL of the HTTP request. + * + * \return The URL of the HTTP request */ - (OFURL*)URL; /** - * Sets the request type for the HTTP request. + * \brief Sets the request type of the HTTP request. * - * \param requestType The request type for the HTTP request + * \param requestType The request type of the HTTP request */ - (void)setRequestType: (of_http_request_type_t)requestType; /** - * \return The request type for the HTTP request + * \brief Returns the request type of the HTTP request. + * + * \return The request type of the HTTP request */ - (of_http_request_type_t)requestType; /** - * Sets the query string for the HTTP request. + * \brief Sets the query string of the HTTP request. * - * \param queryString The query string for the HTTP request + * \param queryString The query string of the HTTP request */ - (void)setQueryString: (OFString*)queryString; /** - * \return The query string for the HTTP request + * \brief Returns the query string of the HTTP request. + * + * \return The query string of the HTTP request */ - (OFString*)queryString; /** - * Sets a dictionary with headers for the HTTP request. + * \brief Sets a dictionary with headers for the HTTP request. * * \param headers A dictionary with headers for the HTTP request */ - (void)setHeaders: (OFDictionary*)headers; /** + * \brief Retrusn a dictionary with headers for the HTTP request. + * * \return A dictionary with headers for the HTTP request. */ - (OFDictionary*)headers; /** - * Sets whether redirects from HTTPS to HTTP are allowed. + * \brief Sets whether redirects from HTTPS to HTTP are allowed. * * \param allowed Whether redirects from HTTPS to HTTP are allowed */ - (void)setRedirectsFromHTTPSToHTTPAllowed: (BOOL)allowed; /** - * \return Whether redirects from HTTPS to HTTP are allowed + * \brief Returns whether redirects from HTTPS to HTTP will be allowed + * + * \return Whether redirects from HTTPS to HTTP will be allowed */ - (BOOL)redirectsFromHTTPSToHTTPAllowed; /** - * Sets the delegate for the HTTP request. + * \brief Sets the delegate of the HTTP request. * - * \param delegate The delegate for the HTTP request + * \param delegate The delegate of the HTTP request */ - (void)setDelegate: (id )delegate; /** - * \return The delegate for the HTTP request. + * \brief Returns the delegate of the HTTP reqeust. + * + * \return The delegate of the HTTP request */ - (id )delegate; /** - * Sets whether an OFDataArray with the data is created. + * \brief Sets whether an OFDataArray with the data should be created. * * Setting this to NO is only useful if you are using the delegate to handle the * data. * * \param storesData Whether to store the data in an OFDataArray */ - (void)setStoresData: (BOOL)storesData; /** - * \return Whether an OFDataArray with the data is created + * \brief Returns whether an OFDataArray with the date should be created. + * + * \return Whether an OFDataArray with the data should be created */ - (BOOL)storesData; /** - * Performs the HTTP request and returns an OFHTTPRequestResult. + * \brief Performs the HTTP request and returns an OFHTTPRequestResult. * * \return An OFHTTPRequestResult with the result of the HTTP request */ - (OFHTTPRequestResult*)perform; /** - * Performs the HTTP request and returns an OFHTTPRequestResult. + * \brief Performs the HTTP request and returns an OFHTTPRequestResult. * * \param redirects The maximum number of redirects after which no further * attempt is done to follow the redirect, but instead the * redirect is returned as an OFHTTPRequest * \return An OFHTTPRequestResult with the result of the HTTP request @@ -253,24 +272,32 @@ headers: (OFDictionary*)headers data: (OFDataArray*)data; /// \endcond /** + * \brief Returns the state code of the result of the HTTP request. + * * \return The status code of the result of the HTTP request */ - (short)statusCode; /** - * \return The HTTP headers of the result of the HTTP request + * \brief Returns the headers of the result of the HTTP request. + * + * \return The headers of the result of the HTTP request */ - (OFDictionary*)headers; /** - * \return The data returned for the HTTP request + * \brief Returns the data received for the HTTP request. + * + * Returns nil if storesData was set to NO. + * + * \return The data received for the HTTP request */ - (OFDataArray*)data; @end @interface OFObject (OFHTTPRequestDelegate) @end extern Class of_http_request_tls_socket_class; Index: src/OFHash.h ================================================================== --- src/OFHash.h +++ src/OFHash.h @@ -27,34 +27,44 @@ #ifdef OF_HAVE_PROPERTIES @property (readonly) BOOL isCalculated; #endif /** - * \return The digest size of the hash, in byte. + * \brief Returns the digest size of the hash, in bytes. + * + * \return The digest size of the hash, in bytes */ + (size_t)digestSize; /** - * \return The block size of the hash, in byte. + * \brief Returns the block size of the hash, in bytes. + * + * \return The block size of the hash, in bytes */ + (size_t)blockSize; /** - * Adds a buffer to the hash to be calculated. + * \brief Adds a buffer to the hash to be calculated. * * \param buf The buffer which should be included into the calculation. * \param length The length of the buffer */ - (void)updateWithBuffer: (const char*)buf length: (size_t)length; /** - * \return A buffer containing the hash. The size of the buffer is depending - * on the hash used. The buffer is part of object's memory pool. + * \brief Returns a buffer containing the hash. + * + * The size of the buffer depends on the hash used. The buffer is part of the + * receiver's memory pool. + * + * \return A buffer containing the hash */ - (uint8_t*)digest; /** + * \brief Returns a boolean whether the hash has already been calculated. + * * \return A boolean whether the hash has already been calculated */ - (BOOL)isCalculated; @end Index: src/OFList.h ================================================================== --- src/OFList.h +++ src/OFList.h @@ -49,46 +49,53 @@ @property (readonly) of_list_object_t *firstListObject; @property (readonly) of_list_object_t *lastListObject; #endif /** + * \brief Creates a new OFList. + * * \return A new autoreleased OFList */ + list; /** - * \return The first list object in the list + * \brief Returns the first list object of the list. + * + * \return The first list object of the list */ - (of_list_object_t*)firstListObject; /** - * \return The last list object in the list + * \brief Retrusn the last list object of the list. + * + * \return The last list object of the list */ - (of_list_object_t*)lastListObject; /** - * Appends an object to the list. + * \brief Appends an object to the list. * * \param object The object to append * \return An of_list_object_t, needed to identify the object inside the list. * For example, if you want to remove an object from the list, you need * its of_list_object_t. */ - (of_list_object_t*)appendObject: (id)object; /** - * Prepends an object to the list. + * \brief Prepends an object to the list. * * \param object The object to prepend * \return An of_list_object_t, needed to identify the object inside the list. * For example, if you want to remove an object from the list, you need * its of_list_object_t. */ - (of_list_object_t*)prependObject: (id)object; /** - * Inserts an object before another object. + * \brief Inserts an object before another list object. + * * \param object The object to insert * \param listObject The of_list_object_t of the object before which it should be * inserted * \return An of_list_object_t, needed to identify the object inside the list. * For example, if you want to remove an object from the list, you need @@ -96,11 +103,12 @@ */ - (of_list_object_t*)insertObject: (id)object beforeListObject: (of_list_object_t*)listObject; /** - * Inserts an object after another object. + * \brief Inserts an object after another list object. + * * \param object The object to insert * \param listObject The of_list_object_t of the object after which it should be * inserted * \return An of_list_object_t, needed to identify the object inside the list. * For example, if you want to remove an object from the list, you need @@ -108,11 +116,11 @@ */ - (of_list_object_t*)insertObject: (id)object afterListObject: (of_list_object_t*)listObject; /** - * Removes the object with the specified list object from the list. + * \brief Removes the object with the specified list object from the list. * * \param listObject The list object returned by append / prepend */ - (void)removeListObject: (of_list_object_t*)listObject; @end Index: src/OFMD5Hash.h ================================================================== --- src/OFMD5Hash.h +++ src/OFMD5Hash.h @@ -30,9 +30,11 @@ uint32_t u32[16]; } in; } /** - * \return A new autoreleased MD5 Hash + * \brief Creates a new OFMD5Hash. + * + * \return A new autoreleased OFMD5Hash */ + MD5Hash; @end Index: src/OFMutableArray.h ================================================================== --- src/OFMutableArray.h +++ src/OFMutableArray.h @@ -27,95 +27,96 @@ { unsigned long mutations; } /** - * Adds an object to the OFArray. + * \brief Adds an object to the OFArray. * * \param object An object to add */ - (void)addObject: (id)object; /** - * Adds an object to the OFArray at the specified index. + * \brief Adds an object to the OFArray at the specified index. * * \param object An object to add * \param index The index where the object should be added */ - (void)addObject: (id)object atIndex: (size_t)index; /** - * Replaces the first object equivalent to the first specified object with the - * second specified object. + * \brief Replaces the first object equivalent to the specified object with the + * other specified object. * * \param oldObject The object to replace * \param newObject The replacement object */ - (void)replaceObject: (id)oldObject withObject: (id)newObject; /** - * Replaces the object at the specified index with the specified object. + * \brief Replaces the object at the specified index with the specified object. * * \param index The index of the object to replace * \param object The replacement object */ - (void)replaceObjectAtIndex: (size_t)index withObject: (id)object; /** - * Replaces the first object that has the same address as the first specified - * object with the second specified object. + * \brief Replaces the first object that has the same address as the specified + * object with the other specified object. * * \param oldObject The object to replace * \param newObject The replacement object */ - (void)replaceObjectIdenticalTo: (id)oldObject withObject: (id)newObject; /** - * Removes the first object equivalent to the specified object. + * \brief Removes the first object equivalent to the specified object. * * \param object The object to remove */ - (void)removeObject: (id)object; /** - * Removes the first object that has the same address as the specified object. + * \brief Removes the first object that has the same address as the specified + * object. * * \param object The object to remove */ - (void)removeObjectIdenticalTo: (id)object; /** - * Removes the object at the specified index. + * \brief Removes the object at the specified index. * * \param index The index of the object to remove */ - (void)removeObjectAtIndex: (size_t)index; /** - * Removes the specified amount of objects from the end of the OFArray. + * \brief Removes the specified amount of objects from the end of the OFArray. * * \param nObjects The number of objects to remove */ - (void)removeNObjects: (size_t)nObjects; /** - * Removes the specified amount of objects at the specified index. + * \brief Removes the specified amount of objects at the specified index. * * \param nobjects The number of objects to remove * \param index The index at which the objects are removed */ - (void)removeNObjects: (size_t)nObjects atIndex: (size_t)index; #ifdef OF_HAVE_BLOCKS /** - * Replaces each object with the object returned by the block. + * \brief Replaces each object with the object returned by the block. * * \param block The block which returns a new object for each object */ - (void)replaceObjectsUsingBlock: (of_array_replace_block_t)block; #endif @end Index: src/OFMutableDictionary.h ================================================================== --- src/OFMutableDictionary.h +++ src/OFMutableDictionary.h @@ -27,30 +27,31 @@ { unsigned long mutations; } /** - * Sets an object for a key. - * A key can be any object. + * \brief Sets an object for a key. + * + * A key can be any object that conforms to the OFCopying protocol. * * \param key The key to set * \param object The object to set the key to */ - (void)setObject: (id)object forKey: (id )key; /** - * Remove the object with the given key from the dictionary. + * \brief Removes the object for the specified key from the dictionary. * * \param key The key whose object should be removed */ - (void)removeObjectForKey: (id)key; #ifdef OF_HAVE_BLOCKS /** - * Replaces each object with the object returned by the block. + * \brief Replaces each object with the object returned by the block. * * \param block The block which returns a new object for each object */ - (void)replaceObjectsUsingBlock: (of_dictionary_replace_block_t)block; #endif @end