save

[protos/libecoli.git] / lib / ecoli_keyval.h

diff --git a/lib/ecoli_keyval.h b/lib/ecoli_keyval.h
index 30232d0..3d739ff 100644 (file)
--- a/lib/ecoli_keyval.h
+++ b/lib/ecoli_keyval.h
@@ -25,6 +25,13 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * Simple hash table API
+ *
+ * This file provides functions to store objects in hash tables, using strings
+ * as keys.
+ */
+
 #ifndef ECOLI_KEYVAL_
 #define ECOLI_KEYVAL_
 
@@ -35,16 +42,95 @@ typedef void (*ec_keyval_elt_free_t)(void *);
 
 struct ec_keyval;
 
+/**
+ * Create a hash table.
+ *
+ * @return
+ *   The hash table, or NULL on error (errno is set).
+ */
 struct ec_keyval *ec_keyval(void);
 
+/**
+ * Get a value from the hash table.
+ *
+ * @param keyval
+ *   The hash table.
+ * @param key
+ *   The key string.
+ * @return
+ *   The element if it is found, or NULL on error (errno is set).
+ *   In case of success but the element is NULL, errno is set to 0.
+ */
 void *ec_keyval_get(const struct ec_keyval *keyval, const char *key);
+
+/**
+ * Check if the hash table contains this key.
+ *
+ * @param keyval
+ *   The hash table.
+ * @param key
+ *   The key string.
+ * @return
+ *   true if it contains the key, else false.
+ */
 bool ec_keyval_has_key(const struct ec_keyval *keyval, const char *key);
+
+/**
+ * Delete an object from the hash table.
+ *
+ * @param keyval
+ *   The hash table.
+ * @param key
+ *   The key string.
+ * @return
+ *   0 on success, or -1 on error (errno is set).
+ */
 int ec_keyval_del(struct ec_keyval *keyval, const char *key);
+
+/**
+ * Add/replace an object in the hash table.
+ *
+ * @param keyval
+ *   The hash table.
+ * @param key
+ *   The key string.
+ * @param val
+ *   The pointer to be saved in the hash table.
+ * @param free_cb
+ *   An optional pointer to a destructor function called when an
+ *   object is destroyed (ec_keyval_del() or ec_keyval_free()).
+ * @return
+ *   0 on success, or -1 on error (errno is set).
+ */
 int ec_keyval_set(struct ec_keyval *keyval, const char *key, void *val,
        ec_keyval_elt_free_t free_cb);
 
+/**
+ * Free a hash table an all its objects.
+ *
+ * @param keyval
+ *   The hash table.
+ */
 void ec_keyval_free(struct ec_keyval *keyval);
+
+/**
+ * Get the length of a hash table.
+ *
+ * @param keyval
+ *   The hash table.
+ * @return
+ *   The length of the hash table.
+ */
 size_t ec_keyval_len(const struct ec_keyval *keyval);
-void ec_keyval_dump(const struct ec_keyval *keyval, FILE *out);
+
+/**
+ * Dump a hash table.
+ *
+ * @param out
+ *   The stream where the dump is sent.
+ * @param keyval
+ *   The hash table.
+ */
+void ec_keyval_dump(FILE *out, const struct ec_keyval *keyval);
 
 #endif