Add documentation, expand error handling, implement file and buffer io

include/bh/queue.h

@@ -5,152 +5,31 @@
 
 typedef struct bh_queue_s bh_queue_t;
 
-/**
- * @brief   Create new queue object.
- *
- * @return  If the function succeeds, the return value is a pointer to the new
- *          queue object.
- * @return  If the function fails, the return value is NULL.
- *
- * @sa      bh_queue_free, bh_queue_reserve, bh_queue_insert
- */
 bh_queue_t *bh_queue_new(void);
 
-/**
- * @brief   Free queue object.
- *
- * @param   queue   Valid pointer to the queue object.
- *
- * @sa      bh_queue_clear
- */
 void bh_queue_free(bh_queue_t *queue);
 
-/**
- * @brief   Clear the queue.
- *
- * @param   queue   Valid pointer to the queue object.
- *
- * @warning Calling this function will invalidate iterators.
- *
- * @sa      bh_queue_remove
- */
 void bh_queue_clear(bh_queue_t *queue);
 
-/**
- * @brief   Reserve space for the specified amount of elements.
- *
- * @param   queue   Valid pointer to the queue object.
- * @param   size    The amount of elements.
- *
- * @return  If the function succeeds, the return value is zero.
- * @return  If the function fails, the return value is non-zero.
- *
- * @warning Calling this function will invalidate iterators.
- *
- * @sa      bh_queue_capacity, bh_queue_insert
- */
 int bh_queue_reserve(bh_queue_t *queue,
                      size_t size);
 
-/**
- * @brief   Insert element at the end of the queue.
- *
- * @param   queue   Valid pointer to the queue object.
- * @param   value   Element.
- *
- * @return  If the function succeeds, the return value is zero.
- * @return  If the function fails, the return value is non-zero.
- *
- * @warning Inserted element is owned by the caller of the function.
- * @warning Calling this function will invalidate iterators.
- *
- * @sa      bh_queue_remove, bh_queue_front
- */
 int bh_queue_insert(bh_queue_t *queue,
                     void *value);
 
-/**
- * @brief   Remove element from the front of the queue.
- *
- * @param   queue   Valid pointer to the queue object.
- *
- * @warning Calling this function will invalidate iterators.
- *
- * @sa      bh_queue_insert, bh_queue_front
- */
 void bh_queue_remove(bh_queue_t *queue);
 
-/**
- * @brief   Return element from the front of the queue.
- *
- * @param   queue   Valid pointer to the queue object.
- *
- * @return  If the function succeeds, the return value is a valid pointer to
- *          the element.
- * @return  If the function fails, the return value is NULL.
- *
- * @sa      bh_queue_empty, bh_queue_insert
- */
 void *bh_queue_front(bh_queue_t *queue);
 
-/**
- * @brief   Check if the queue is empty.
- *
- * @param   queue   Valid pointer to the queue object.
- *
- * @return  The return value is non-zero if the queue is empty, otherwise zero.
- *
- * @sa      bh_queue_size
- */
 int bh_queue_empty(bh_queue_t *queue);
 
-/**
- * @brief   Return queue size.
- *
- * @param   queue   Valid pointer to the queue object.
- *
- * @return  The return value is current queue size.
- *
- * @sa      bh_queue_empty, bh_queue_capacity
- */
 size_t bh_queue_size(bh_queue_t *queue);
 
-/**
- * @brief   Return queue capacity.
- *
- * @param   queue   Valid pointer to the queue object.
- *
- * @return  The return value is current queue capacity.
- *
- * @sa      bh_queue_reserve, bh_queue_size
- */
 size_t bh_queue_capacity(bh_queue_t *queue);
 
-/**
- * @brief   Return iterator for the next element in the queue.
- *
- * @param   queue   Valid pointer to the queue object.
- * @param   iter    Valid or NULL iterator.
- *
- * @return  The return value is the valid iterator for the next element in the
- *          queue.
- * @return  The return value is the NULL iterator if there is no more elements
- *          in the queue.
- *
- * @sa      bh_queue_iter_value
- */
 void *bh_queue_iter_next(bh_queue_t *queue,
                          void *iter);
 
-/**
- * @brief   Return pointer to the element's value.
- *
- * @param   iter    Valid iterator.
- *
- * @return  The return value is the stored element.
- *
- * @sa      bh_queue_iter_next
- */
 void *bh_queue_iter_value(void *iter);
 
 #endif /* BH_QUEUE_H */