Fix function documentation, add missing function

include/BH/Algo.h

@@ -6,10 +6,10 @@
 
 
 /**
- * Exchanges the values of two elements.
+ * Exchanges values between \a src and \a dest elements of sizze \a size.
  *
- * \param dest	Pointer to the element
+ * \param dest	Destination element pointer
- * \param src	Pointer to the element
+ * \param src	Source element pointer
  * \param size	Element size in bytes
  */
 void BH_Swap(void *dest,
@@ -18,14 +18,15 @@ void BH_Swap(void *dest,
 
 
 /**
- * Partitions the array relative to the specified pivot element.
+ * Partitions the \a array (with specified \a size and \a element size)
+ * relative to specified \a pivot element.
  *
- * The pivot element can be part of the partitioned array.
+ * The \a pivot element can be part of the partitioned \a array.
  *
- * \param pivot     Pointer to the pivot element
+ * \param pivot    Pivot element pointer
- * \param array     Pointer to the array
+ * \param array    Array pointer
  * \param size     Array size
- * \param element   Element size in bytes
+ * \param element  Array element size
  * \param equal    Comparision function
  *
  * \return Pointer to the first element of the second partition.
@@ -38,11 +39,14 @@ void *BH_Partition(void *pivot,
 
 
 /**
- * Sorts the array.
+ * Sorts the \a array (with specified \a size and \a element size).
  *
- * \param array     Pointer to the array
+ * The sorting algorithm is implementation defined and may change between
+ * revisions.
+ *
+ * \param array    Array pointer
  * \param size     Array size
- * \param element   Element size in bytes
+ * \param element  Array element size
  * \param equal    Comparision function
  */
 void BH_Sort(void *array,
@@ -52,11 +56,11 @@ void BH_Sort(void *array,
 
 
 /**
- * Makes heap in an array from the array.
+ * Heapifies an \a array (with specified \a size and \a element size).
  *
- * \param array     Pointer to the array
+ * \param array    Array pointer
  * \param size     Array size
- * \param element   Element size in bytes
+ * \param element  Array element size
  * \param equal    Comparision function
  */
 void BH_HeapMake(void *array,
@@ -66,11 +70,12 @@ void BH_HeapMake(void *array,
 
 
 /**
- * Removes top/first element from a heap in an array.
+ * Removes top value from the heapified \a array (with specified \a size
+ * and \a element size).
  *
- * \param array     Pointer to the array
+ * \param array     Array pointer
  * \param size      Array size
- * \param element   Element size in bytes
+ * \param element   Array element size
  * \param equal     Comparasion function
  */
 void BH_HeapRemove(void *array,
@@ -80,15 +85,16 @@ void BH_HeapRemove(void *array,
 
 
 /**
- * Inserts new element into heap in an array.
+ * Inserts new \a value into heapified \a array in an array (with specified
+ * \a size and \a element size)
  *
- * If the pointer to value is NULL, this function assumes that the new value
+ * If \a value pointer is NULL, it is assumed that new value is placed at the
- * is at the end of the array.
+ * end of the array.
  *
- * \param value     Pointer to the value
+ * \param value    Value pointer
- * \param array     Pointer to the array
+ * \param array    Array pointer
  * \param size     Array size
- * \param element   Element size in bytes
+ * \param element  Array element size
  * \param equal    Comparasion function
  */
 void BH_HeapInsert(void *value,
@@ -99,21 +105,16 @@ void BH_HeapInsert(void *value,
 
 
 /**
- * Removes top/first element and inserts new element into heap in an array.
+ * Removes top value from heapified \a array (with specified \a size and
+ * \a element size) and inserts new \a value.
  *
- * If the pointer to value is NULL, this function assumes that the new value
+ * If value pointer is NULL, it is assumed that new value is placed at the
- * is at the end of the array.
+ * end of the array.
  *
- * This function is roughly equivalent to the following code:
+ * \param value    Value pointer
- * \code
+ * \param array    Array pointer
- * BH_HeapRemove(array, size, element, equal);
- * BH_HeapInsert(value, array, size - 1, element, equal);
- * \endcode
- *
- * \param value     Pointer to the value
- * \param array     Pointer to the array
  * \param size     Array size
- * \param element   Element size in bytes
+ * \param element  Array element size
  * \param equal    Comparasion function
  */
 void BH_HeapReplace(void *value,

include/BH/Hashmap.h

@@ -9,12 +9,12 @@ typedef struct BH_Hashmap BH_Hashmap;
 
 
 /**
- * Creates the new hashmap handle.
+ * Creates the new hashmap with specified \a equal and \a hash callbacks.
  *
  * \param equal  Comparision function
  * \param hash   Key hash function
  *
- * \return On success, returns hashmap handle.
+ * \return On success, returns hashmap pointer.
  * \return On failure, returns a null pointer.
  */
 BH_Hashmap *BH_HashmapNew(BH_EqualCallback equal,
@@ -22,34 +22,34 @@ BH_Hashmap *BH_HashmapNew(BH_EqualCallback equal,
 
 
 /**
- * Destroys the hashmap.
+ * Destroys the \a hashmap.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  */
 void BH_HashmapFree(BH_Hashmap *hashmap);
 
 
 /**
- * Clears the hashmap.
+ * Clears the \a hashmap.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  */
 void BH_HashmapClear(BH_Hashmap *hashmap);
 
 
 /**
- * Reserves space in the hashmap.
+ * Reserves space for \a size amount of elements in the \a hashmap.
  *
  * This function can both expand and shrink the available space in hashmap.
  * This function takes into account current hashmap load factor.
  *
- * \param hashmap  Hahsmap handle
+ * \param hashmap  Hahsmap pointer
  * \param size     Capacity
  *
  * \note Calling this function will invalidate iterators.
  * \note Actual hashmap capacity can be bigger then requested.
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_HashmapReserve(BH_Hashmap *hashmap,
@@ -57,16 +57,16 @@ int BH_HashmapReserve(BH_Hashmap *hashmap,
 
 
 /**
- * Inserts the pair of key-value into the hashmap.
+ * Inserts the pair \a key \a value pair into the \a hashmap.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  * \param key      Key
  * \param value    Value
  *
  * \note This function allows duplicates to be inserted.
  * \note Calling this function will invalidate iterators.
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_HashmapInsert(BH_Hashmap *hashmap,
@@ -75,9 +75,9 @@ int BH_HashmapInsert(BH_Hashmap *hashmap,
 
 
 /**
- * Removes value from the hashmap.
+ * Removes value from the \a hashmap by \a key.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  * \param key      Key
  *
  * \note Calling this function will invalidate iterators.
@@ -89,13 +89,13 @@ void BH_HashmapRemove(BH_Hashmap *hashmap,
 
 
 /**
- * Returns value from the hashmap by key.
+ * Returns \a value from the \a hashmap by \a key.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  * \param key      Key
  * \param value    Value (optional)
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_HashmapAt(BH_Hashmap *hashmap,
@@ -104,20 +104,20 @@ int BH_HashmapAt(BH_Hashmap *hashmap,
 
 
 /**
- * Checks if the hashmap is empty.
+ * Checks if the \a hashmap is empty.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  *
  * \return If hashmap is empty, returns non-zero value
- * \return If hashmap is not empty, returns zero value
+ * \return If hashmap is not empty, returns zero
  */
 int BH_HashmapEmpty(BH_Hashmap *hashmap);
 
 
 /**
- * Returns the size of the hashmap.
+ * Returns the size of the \a hashmap.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  *
  * \return Returns the size of the hashmap.
  */
@@ -125,9 +125,9 @@ size_t BH_HashmapSize(BH_Hashmap *hashmap);
 
 
 /**
- * Returns the capacity of the hashmap.
+ * Returns the capacity of the \a hashmap.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  *
  * \return Returns the capacity of the hashmap.
  */
@@ -135,9 +135,9 @@ size_t BH_HashmapCapacity(BH_Hashmap *hashmap);
 
 
 /**
- * Returns the load factor of the hashmap.
+ * Returns the load factor of the \a hashmap.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  *
  * \return Returns the load factor of the hashmap.
  */
@@ -145,9 +145,9 @@ float BH_HashmapFactor(BH_Hashmap *hashmap);
 
 
 /**
- * Sets the load factor of the hashmap.
+ * Sets the load \a factor of the \a hashmap.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  * \param factor   Load factor
  *
  * \note New load factor will be applied on the next reserve/insert operation.
@@ -157,9 +157,9 @@ void BH_HashmapSetFactor(BH_Hashmap *hashmap,
 
 
 /**
- * Returns the iterator to the element in the hashmap with specified key.
+ * Returns the iterator to the element in the \a hashmap by \a key.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  * \param iter     Iterator
  *
  * \return On success, returns iterator value.
@@ -173,12 +173,12 @@ void *BH_HashmapIterAt(BH_Hashmap *hashmap,
 
 
 /**
- * Returns the iterator to the next element in the hashmap.
+ * Returns next element \a iter in the \a hashmap.
  *
- * If the iterator is NULL pointer, this function will return iterator to the
+ * If \a iter is NULL pointer, then this function will return iter to the
  * first element of the hashmap.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  * \param iter     Iterator
  *
  * \return On success, returns new iterator value for the next element.
@@ -189,9 +189,9 @@ void *BH_HashmapIterNext(BH_Hashmap *hashmap,
 
 
 /**
- * Removes value from the hashmap pointed by by iterator.
+ * Removes key-value from the \a hashmap pointed by \a iter.
  *
- * \param hashmap  Hashmap handle
+ * \param hashmap  Hashmap pointer
  * \param iter     Iterator
  *
  * \note Calling this function will invalidate iterators.
@@ -201,7 +201,7 @@ void BH_HashmapIterRemove(BH_Hashmap *hashmap,
 
 
 /**
- * Returns key, pointed by the iterator.
+ * Returns key, pointed by the \a iter.
  *
  * \param iter  Iterator
  *
@@ -211,7 +211,7 @@ void *BH_HashmapIterKey(void *iter);
 
 
 /**
- * Returns value, pointed by the iterator.
+ * Returns value, pointed by the \a iter.
  *
  * \param iter  Iterator
  *
@@ -221,3 +221,4 @@ void *BH_HashmapIterValue(void *iter);
 
 
 #endif /* BH_HASHMAP_H */
+

include/BH/IO.h

@@ -48,34 +48,34 @@ typedef int (*BH_IOCallback)(void *, int ,void *, void *);
 
 
 /**
- * Creates the IO handle that represents file.
+ * Creates the IO that represents file with the given \a path.
  *
- * \param path  Path to the file
+ * \param path  File path
  *
- * \return On success, returns IO handle.
+ * \return On success, returns IO pointer.
  * \return On failure, returns NULL pointer.
  */
 BH_IO *BH_FileNew(const char *path);
 
 
 /**
- * Creates the IO handle that represents buffered IO.
+ * Creates the IO that buffers access to other \a io.
  *
- * \param io  IO handle
+ * \param io  IO pointer
  *
- * \return On success, returns IO handle.
+ * \return On success, returns IO pointer.
  * \return On failure, returns NULL pointer.
  */
 BH_IO *BH_BufferNew(BH_IO *io);
 
 
 /**
- * Creates the IO handle with specified handler and context.
+ * Creates the IO with specified callback \a cb and \a data.
  *
- * \param func  IO actions handler
+ * \param cb    Callback
  * \param data  Initialization data
  *
- * \return On success, returns IO handle.
+ * \return On success, returns IO pointer.
  * \return On failure, returns NULL pointer.
  */
 BH_IO *BH_IONew(BH_IOCallback cb,
@@ -83,17 +83,17 @@ BH_IO *BH_IONew(BH_IOCallback cb,
 
 
 /**
- * Destroys the IO.
+ * Destroys the \a io.
  *
- * \param io  IO handle
+ * \param io  IO pointer
  */
 void BH_IOFree(BH_IO *io);
 
 
 /**
- * Returns the IO instance classname.
+ * Returns the \a io classname.
  *
- * \param io  IO handle
+ * \param io  IO pointer
  *
  * \return On success, returns pointer to constant string.
  * \return On failure, returns NULL pointer
@@ -102,12 +102,12 @@ const char *BH_IOClassname(BH_IO* io);
 
 
 /**
- * Opens the IO in specified mode of operation.
+ * Opens the \a io in specified \a mode of operation.
  *
- * \param io    IO handle
+ * \param io    IO pointer
  * \param mode  Mode of operation
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IOOpen(BH_IO *io,
@@ -115,25 +115,25 @@ int BH_IOOpen(BH_IO *io,
 
 
 /**
- * Closes the IO.
+ * Closes the \a io.
  *
- * \param io  IO handle
+ * \param io  IO pointer
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IOClose(BH_IO *io);
 
 
 /**
- * Reads up to specified amount of bytes from the IO into memory buffer.
+ * Reads up to \a size bytes from the \a io into \a buffer.
  *
- * \param io      IO handle
+ * \param io      IO pointer
- * \param buffer  Pointer to the buffer
+ * \param buffer  Buffer pointer
- * \param size    Bytes to read
+ * \param size    Buffer size
- * \param actual  Bytes read
+ * \param actual  Bytes read (optional)
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IORead(BH_IO *io,
@@ -143,14 +143,14 @@ int BH_IORead(BH_IO *io,
 
 
 /**
- * Writes up to specified amount of bytes into the IO from the memory buffer.
+ * Writes up to \a size bytes to the \a io from \a buffer.
  *
- * \param io      IO handle
+ * \param io      IO pointer
- * \param buffer  Pointer to the buffer
+ * \param buffer  Buffer pointer
- * \param size    Bytes to write
+ * \param size    Buffer size
- * \param actual  Bytes written
+ * \param actual  Bytes written (optional)
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IOWrite(BH_IO *io,
@@ -160,14 +160,14 @@ int BH_IOWrite(BH_IO *io,
 
 
 /**
- * Peeks up to specified amount of bytes from the IO handle.
+ * Peeks up to \a size bytes from \a io into \a buffer.
  *
- * \param io  IO handle
+ * \param io      IO pointer
- * \param buffer  Pointer to the buffer
+ * \param buffer  Buffer pointer
- * \param size    Bytes to peek
+ * \param size    Buffer size
- * \param actial  Bytes peeked
+ * \param actial  Bytes peeked (optional)
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IOPeek(BH_IO *io,
@@ -177,12 +177,12 @@ int BH_IOPeek(BH_IO *io,
 
 
 /**
- * Tells current offset in the IO.
+ * Tells current \a position in the \a io.
  *
- * \param io        IO handle
+ * \param io        IO pointer
- * \param position  Offset
+ * \param position  Position
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IOTell(BH_IO *io,
@@ -190,13 +190,13 @@ int BH_IOTell(BH_IO *io,
 
 
 /**
- * Seeks to specified offset in the IO.
+ * Seeks to specified \a position and \a direction in the \a io.
  *
- * \param io         IO handle
+ * \param io         IO pointer
- * \param position   Offset
+ * \param position   Position
  * \param direction  Direction
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IOSeek(BH_IO *io,
@@ -205,23 +205,23 @@ int BH_IOSeek(BH_IO *io,
 
 
 /**
- * Flushes the internal buffers of the IO.
+ * Flushes the internal buffers of the \a io.
  *
- * \param io  IO handle
+ * \param io  IO pointer
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IOFlush(BH_IO *io);
 
 
 /**
- * Returns the size of the IO (either total or available size).
+ * Returns total or available size of the \a io.
  *
- * \param io    IO handle
+ * \param io    IO pointer
  * \param size  Available/total size
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IOSize(BH_IO *io,
@@ -229,9 +229,9 @@ int BH_IOSize(BH_IO *io,
 
 
 /**
- * Returns flags of the IO.
+ * Returns flags of the \a io.
  *
- * \param io  IO handle
+ * \param io  IO pointer
  *
  * \return Flags of the IO
  */
@@ -239,11 +239,11 @@ int BH_IOFlags(BH_IO *io);
 
 
 /**
- * Clears errors of the IO.
+ * Clears errors of the \a io.
  *
- * \param io  IO handle
+ * \param io  IO pointer
  *
- * \return On success, returns zero value.
+ * \return On success, returns zero.
  * \return On failure, returns error code.
  */
 int BH_IOClear(BH_IO *io);

include/BH/Queue.h

@@ -9,42 +9,42 @@ typedef struct BH_Queue BH_Queue;
 
 
 /**
- * Creates the new queue object.
+ * Creates the new queue.
  *
- * \return  On success, returns the pointer to the new queue object.
+ * \return  On success, returns the queue pointer.
  * \return  On failure, returns a null pointer.
  */
 BH_Queue *BH_QueueNew(void);
 
 
 /**
- * Frees the \a queue object.
+ * Frees the \a queue.
  *
- * \param queue Pointer to the queue object to be freed
+ * \param queue  Queue pointer
  */
 void BH_QueueFree(BH_Queue *queue);
 
 
 /**
- * Clears the \a queue object.
+ * Clears the \a queue.
  *
- * \param queue Pointer to the queue object to be cleared
+ * \param queue  Queue pointer
  */
 void BH_QueueClear(BH_Queue *queue);
 
 
 /**
- * Reserves the space for \a size elements in the \a queue.
+ * Reserves the space for \a size amount of value in the \a queue.
  *
- * This function can both expand and shrink the available space in \a queue.
+ * This function can both expand and shrink the available space in queue.
  *
- * \param queue Pointer to the queue object to be resized in terms of capacity
+ * \param queue  Queue pointer
- * \param size  New capacity of the queue
+ * \param size   Capacity
  *
  * \note Calling this function will invalidate iterators.
- * \note Actual hashmap capacity can be bigger then requested.
+ * \note Actual queue capacity can be bigger then requested.
  *
- * \return  On success, returns zero value.
+ * \return  On success, returns zero.
  * \return  On failure, returns error code.
  */
 int BH_QueueReserve(BH_Queue *queue,
@@ -54,12 +54,12 @@ int BH_QueueReserve(BH_Queue *queue,
 /**
  * Inserts the \a value into the \a queue.
  *
- * \param queue Pointer to the queue object
+ * \param queue  Queue pointer
- * \param value Value to be inserted
+ * \param value  Value
  *
  * \note Calling this function will invalidate iterators.
  *
- * \return  On success, returns zero value.
+ * \return  On success, returns zero.
  * \return  On failure, returns error code.
  */
 int BH_QueueInsert(BH_Queue *queue,
@@ -69,7 +69,7 @@ int BH_QueueInsert(BH_Queue *queue,
 /**
  * Removes front value from the \a queue.
  *
- * \param queue Pointer to the queue object
+ * \param queue  Queue pointer
  *
  * \note Calling this function will invalidate iterators.
  */
@@ -77,12 +77,13 @@ void BH_QueueRemove(BH_Queue *queue);
 
 
 /**
- * Returns front value from the \a queue.
+ * Returns front \a value from the \a queue.
  *
- * \param queue Pointer to the queue object
+ * \param queue  Queue pointer
+ * \param value  Value
  *
- * \return  On success, returns front value from the queue.
+ * \return  On success, returns zero.
- * \return  On failure, returns null pointer.
+ * \return  On failure, returns error code.
  */
 int BH_QueueFront(BH_Queue *queue,
                   void **value);
@@ -91,10 +92,10 @@ int BH_QueueFront(BH_Queue *queue,
 /**
  * Checks if the \a queue is empty.
  *
- * \param queue Pointer to the queue object
+ * \param queue  Queue pointer
  *
  * \return  If queue is empty, returns non-zero value
- * \return  If queue is not empty, returns zero value
+ * \return  If queue is not empty, returns zero
  */
 int BH_QueueEmpty(BH_Queue *queue);
 
@@ -102,7 +103,7 @@ int BH_QueueEmpty(BH_Queue *queue);
 /**
  * Returns the size of the \a queue.
  *
- * \param queue Pointer to the queue object
+ * \param queue  Queue pointer
  *
  * \return  Returns the size of the queue.
  */
@@ -112,7 +113,7 @@ size_t BH_QueueSize(BH_Queue *queue);
 /**
  * Returns the capacity of the \a queue.
  *
- * \param queue Pointer to the queue object
+ * \param queue  Queue pointer
  *
  * \return  Returns the capacity of the queue.
  */
@@ -122,24 +123,20 @@ size_t BH_QueueCapacity(BH_Queue *queue);
 /**
  * Returns the iterator to the next element in the \a queue.
  *
- * \param queue Pointer to the queue object
+ * \param queue  Queue pointer
- * \param iter  Opaque iterator value
+ * \param iter   Iterator
  *
- * \return  If the \a iter doesn't point to the last element of the queue,
+ * \return On success, returns new iterator value for the next element.
- *          returns next iterator value.
+ * \return On failure, returns NULL pointer.
- * \return  If the \a iter point to the last element of the queue, returns
- *          null pointer.
- * \return  If the \a iter is the null pointer, returns iterator to the
- *          first element of the queue.
  */
 void *BH_QueueIterNext(BH_Queue *queue,
                        void *iter);
 
 
 /**
- * Returns the value, pointed by the queue iterator \a iter.
+ * Returns the value, pointed by the \a iter.
  *
- * \param iter  Opaque iterator value
+ * \param iter  Iterator
  *
  * \return  Returns value, pointed by iterator.
  */

src/IO.c

@@ -224,3 +224,11 @@ int BH_IOClear(BH_IO *io)
     /* Call the IO device clear error handler */
     return io->cb(io + 1, BH_IO_CLEAR_CB, NULL, NULL);
 }
+
+
+
+BH_IO *BH_BufferNew(BH_IO *io)
+{
+    (void)io;
+    return NULL;
+}