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

include/bh/hashmap.h

@@ -1,231 +1,53 @@
-#ifndef BHLIB_HASHMAP_H
-#define BHLIB_HASHMAP_H
+#ifndef BH_HASHMAP_H
+#define BH_HASHMAP_H
 
 #include "bh.h"
 
 typedef struct bh_hashmap_s bh_hashmap_t;
 
-/**
- * @brief   Create new hashmap object.
- *
- * @param   equal   Function used for comparing keys
- * @param   hash    Function used to calculate hash value of the key
- *
- * @return  If the function succeeds, the return value is a pointer to the new
- *          hashmap object.
- * @return  If the function fails, the return value is NULL.
- *
- * @sa      bh_hashmap_free, bh_hashmap_reserve, bh_hashmap_insert
- */
 bh_hashmap_t *bh_hashmap_new(bh_equal_cb_t equal,
                              bh_hash_cb_t hash);
 
-/**
- * @brief   Free hashmap object.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- *
- * @sa      bh_hashmap_clear
- */
 void bh_hashmap_free(bh_hashmap_t *hashmap);
 
-/**
- * @brief   Clear the hashmap.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- *
- * @warning Calling this function will invalidate iterators.
- *
- * @sa      bh_hashmap_remove
- */
 void bh_hashmap_clear(bh_hashmap_t *hashmap);
 
-/**
- * @brief   Reserve space for the specified amount of elements.
- *
- * @param   hashmap Valid pointer to the hashmap 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_hashmap_capacity, bh_hashmap_insert
- */
 int bh_hashmap_reserve(bh_hashmap_t *hashmap,
                         size_t size);
 
-/**
- * @brief   Insert key/value into the hashmap.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- * @param   key     Key
- * @param   value   Value
- *
- * @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_hashmap_remove, bh_hashmap_at
- */
 int bh_hashmap_insert(bh_hashmap_t *hashmap,
                       void *key,
                       void *value);
 
-/**
- * @brief   Remove element from the hashmap.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- * @param   key     Key.
- *
- * @warning Calling this function will invalidate iterators.
- *
- * @sa      bh_hashmap_insert, bh_hashmap_at
- */
 void bh_hashmap_remove(bh_hashmap_t *hashmap,
                        void *key);
 
-/**
- * @brief   Return element value by the key from the hashmap.
- *
- * @param   hashmap Valid pointer to the hashmap.
- * @param   key     Key.
- * @param   exists  Optional pointer to the exists flag.
- *
- * @return  If the function succeeds, the return value is a valid pointer to
- *          the element value.
- * @return  If the function fails, the return value is NULL.
- *
- * @sa      bh_hashmap_empty, bh_hashmap_insert
- */
 void *bh_hashmap_at(bh_hashmap_t *hashmap,
                     void *key,
                     int *exists);
 
-/**
- * @brief   Check if the hashmap is empty.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- *
- * @return  The return value is non-zero if the hashmap is empty, otherwise
- *          zero.
- *
- * @sa      bh_hashmap_size
- */
 int bh_hashmap_empty(bh_hashmap_t *hashmap);
 
-/**
- * @brief   Return hashmap size.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- *
- * @return  The return value is current hashmap size.
- *
- * @sa      bh_hashmap_empty, bh_hashmap_capacity
- */
 size_t bh_hashmap_size(bh_hashmap_t *hashmap);
 
-/**
- * @brief   Return hashmap capacity.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- *
- * @return  The return value is current hashmap capacity.
- *
- * @sa      bh_hashmap_reserve, bh_hashmap_size
- */
 size_t bh_hashmap_capacity(bh_hashmap_t *hashmap);
 
-/**
- * @brief   Return hashmap load factor.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- *
- * @return  The return value is current hashmap load factor.
- *
- * @sa      bh_hashmap_set_factor, bh_hashmap_capacity
- */
 float bh_hashmap_factor(bh_hashmap_t *hashmap);
 
-/**
- * @brief   Set hashmap load factor.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- * @param   factor  Load factor.
- *
- * @sa      bh_hashmap_factor
- */
 void bh_hashmap_set_factor(bh_hashmap_t *hashmap,
                            float factor);
 
-/**
- * @brief   Return iterator for the element by the key.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- * @param   key     Key
- *
- * @return  The return value is the valid iterator for the element in the
- *          hashmap.
- * @return  The return value is the NULL iterator if there is no element with
- *          specified key.
- *
- * @sa      bh_hashmap_iter_key, bh_hashmap_iter_value
- */
 void *bh_hashmap_iter_at(bh_hashmap_t *hashmap,
                          void *key);
 
-/**
- * @brief   Return iterator for the next element in the hashmap.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- * @param   iter    Valid or NULL iterator.
- *
- * @return  The return value is the valid iterator for the next element in the
- *          hashmap.
- * @return  The return value is the NULL iterator if there is no more elements
- *          in the hashmap.
- *
- * @sa      bh_hashmap_iter_key, bh_hashmap_iter_value
- */
 void *bh_hashmap_iter_next(bh_hashmap_t *hashmap,
                            void *iter);
 
-/**
- * @brief   Remove element from the hashmap by the iterator.
- *
- * @param   hashmap Valid pointer to the hashmap object.
- * @param   key     Valid iterator.
- *
- * @warning Calling this function will invalidate iterators.
- *
- * @sa      bh_hashmap_insert, bh_hashmap_at
- */
 void bh_hashmap_iter_remove(bh_hashmap_t *hashmap,
                             void *iter);
 
-/**
- * @brief   Return pointer to the element's key.
- *
- * @param   iter    Valid iterator.
- *
- * @return  The return value is the stored element key.
- *
- * @sa      bh_hashmap_iter_value, bh_hashmap_iter_next
- */
 void *bh_hashmap_iter_key(void *iter);
 
-/**
- * @brief   Return pointer to the element's value.
- *
- * @param   iter    Valid iterator.
- *
- * @return  The return value is the stored element value.
- *
- * @sa      bh_hashmap_iter_key, bh_hashmap_iter_next
- */
 void *bh_hashmap_iter_value(void *iter);
 
-#endif /* BHLIB_HASHMAP_H */
+#endif /* BH_HASHMAP_H */