Squash doxygen warnings, and make a few slight improvements to the docs.

1 files changed, 51 insertions, 27 deletions

diff --git a/linkhash.h b/linkhash.h
index 552dbf8..3c609b6 100644
--- a/linkhash.h
+++ b/linkhash.h
@@ -149,6 +149,10 @@ for(entry = table->head; entry; entry = entry->next)
 
 /**
  * lh_foreach_safe allows calling of deletion routine while iterating.
+ *
+ * @param table a struct lh_table * to iterate over
+ * @param entry a struct lh_entry * variable to hold each element
+ * @param tmp a struct lh_entry * variable to hold a temporary pointer to the next element
  */
 #define lh_foreach_safe(table, entry, tmp) \
 for(entry = table->head; entry && ((tmp = entry->next) || 1); entry = tmp)
@@ -157,6 +161,7 @@ for(entry = table->head; entry && ((tmp = entry->next) || 1); entry = tmp)
 
 /**
  * Create a new linkhash table.
+ *
  * @param size initial table size. The table is automatically resized
  * although this incurs a performance penalty.
  * @param free_fn callback function used to free memory for entries
@@ -178,8 +183,8 @@ extern struct lh_table* lh_table_new(int size,
 				     lh_equal_fn *equal_fn);
 
 /**
- * Convenience function to create a new linkhash
- * table with char keys.
+ * Convenience function to create a new linkhash table with char keys.
+ *
  * @param size initial table size.
  * @param free_fn callback function used to free memory for entries.
  * @return On success, a pointer to the new linkhash table is returned.
@@ -190,8 +195,8 @@ extern struct lh_table* lh_kchar_table_new(int size,
 
 
 /**
- * Convenience function to create a new linkhash
- * table with ptr keys.
+ * Convenience function to create a new linkhash table with ptr keys.
+ *
  * @param size initial table size.
  * @param free_fn callback function used to free memory for entries.
  * @return On success, a pointer to the new linkhash table is returned.
@@ -203,8 +208,10 @@ extern struct lh_table* lh_kptr_table_new(int size,
 
 /**
  * Free a linkhash table.
- * If a callback free function is provided then it is called for all
- * entries in the table.
+ *
+ * If a lh_entry_free_fn callback free function was provided then it is
+ * called for all entries in the table.
+ *
  * @param t table to free.
  */
 extern void lh_table_free(struct lh_table *t);
@@ -212,6 +219,7 @@ extern void lh_table_free(struct lh_table *t);
 
 /**
  * Insert a record into the table.
+ *
  * @param t the table to insert into.
  * @param k a pointer to the key to insert.
  * @param v a pointer to the value to insert.
@@ -223,22 +231,25 @@ extern int lh_table_insert(struct lh_table *t, const void *k, const void *v);
 
 
 /**
- * Insert a record into the table. This one accepts the key's hash in additon
- * to the key. This is an exension to support functions that need to calculate
- * the hash several times and allows them to do it just once and then pass
- * in the hash to all utility functions. Depending on use case, this can be a
- * very considerate performance improvement.
+ * Insert a record into the table using a precalculated key hash.
+ *
+ * The hash h, which should be calculated with lh_get_hash() on k, is provided by
+ *  the caller, to allow for optimization when multiple operations with the same
+ *  key are known to be needed.
+ *
  * @param t the table to insert into.
  * @param k a pointer to the key to insert.
  * @param v a pointer to the value to insert.
  * @param h hash value of the key to insert
- * @param opts opts, a subset of JSON_OBJECT_ADD_* flags is supported
+ * @param opts if set to JSON_C_OBJECT_KEY_IS_CONSTANT, sets lh_entry.k_is_constant
+ *             so t's free function knows to avoid freeing the key.
  */
 extern int lh_table_insert_w_hash(struct lh_table *t, const void *k, const void *v, const unsigned long h, const unsigned opts);
 
 
 /**
- * Lookup a record into the table.
+ * Lookup a record in the table.
+ *
  * @param t the table to lookup
  * @param k a pointer to the key to lookup
  * @return a pointer to the record structure of the value or NULL if it does not exist.
@@ -246,11 +257,12 @@ extern int lh_table_insert_w_hash(struct lh_table *t, const void *k, const void
 extern struct lh_entry* lh_table_lookup_entry(struct lh_table *t, const void *k);
 
 /**
- * Lookup a record into the table. This one accepts the key's hash in additon
- * to the key. This is an exension to support functions that need to calculate
- * the hash several times and allows them to do it just once and then pass
- * in the hash to all utility functions. Depending on use case, this can be a
- * very considerate performance improvement.
+ * Lookup a record in the table using a precalculated key hash.
+ *
+ * The hash h, which should be calculated with lh_get_hash() on k, is provided by
+ *  the caller, to allow for optimization when multiple operations with the same
+ *  key are known to be needed.
+ *
  * @param t the table to lookup
  * @param k a pointer to the key to lookup
  * @param h hash value of the key to lookup
@@ -259,16 +271,18 @@ extern struct lh_entry* lh_table_lookup_entry(struct lh_table *t, const void *k)
 extern struct lh_entry* lh_table_lookup_entry_w_hash(struct lh_table *t, const void *k, const unsigned long h);
 
 /**
- * Lookup a record into the table
+ * Lookup a record into the table.
+ *
  * @param t the table to lookup
  * @param k a pointer to the key to lookup
  * @return a pointer to the found value or NULL if it does not exist.
- * @deprecated Use lh_table_lookup_ex instead.
+ * @deprecated Use lh_table_lookup_ex() instead.
  */
 THIS_FUNCTION_IS_DEPRECATED(extern const void* lh_table_lookup(struct lh_table *t, const void *k));
 
 /**
- * Lookup a record in the table
+ * Lookup a record in the table.
+ *
  * @param t the table to lookup
  * @param k a pointer to the key to lookup
  * @param v a pointer to a where to store the found value (set to NULL if it doesn't exist).
@@ -278,6 +292,7 @@ extern json_bool lh_table_lookup_ex(struct lh_table *t, const void *k, void **v)
 
 /**
  * Delete a record from the table.
+ *
  * If a callback free function is provided then it is called for the
  * for the item being deleted.
  * @param t the table to delete from.
@@ -290,6 +305,7 @@ extern int lh_table_delete_entry(struct lh_table *t, struct lh_entry *e);
 
 /**
  * Delete a record from the table.
+ *
  * If a callback free function is provided then it is called for the
  * for the item being deleted.
  * @param t the table to delete from.
@@ -328,6 +344,9 @@ THIS_FUNCTION_IS_DEPRECATED(void lh_abort(const char *msg, ...));
 int lh_table_resize(struct lh_table *t, int new_size);
 
 
+/**
+ * @deprecated Don't use this outside of linkhash.h:
+ */
 #if !defined(_MSC_VER) || (_MSC_VER > 1800)
 /* VS2010 can't handle inline funcs, so skip it there */
 #define _LH_INLINE inline
@@ -337,10 +356,11 @@ int lh_table_resize(struct lh_table *t, int new_size);
 
 /**
  * Calculate the hash of a key for a given table.
+ *
  * This is an exension to support functions that need to calculate
  * the hash several times and allows them to do it just once and then pass
  * in the hash to all utility functions. Depending on use case, this can be a
- * very considerate performance improvement.
+ * considerable performance improvement.
  * @param t the table (used to obtain hash function)
  * @param k a pointer to the key to lookup
  * @return the key's hash
@@ -352,7 +372,9 @@ static _LH_INLINE unsigned long lh_get_hash(const struct lh_table *t, const void
 
 #undef _LH_INLINE
 
-/* Don't use this outside of linkhash.h: */
+/**
+ * @deprecated Don't use this outside of linkhash.h:
+ */
 #ifdef __UNCONST
 #define _LH_UNCONST(a) __UNCONST(a)
 #else
@@ -360,15 +382,17 @@ static _LH_INLINE unsigned long lh_get_hash(const struct lh_table *t, const void
 #endif
 
 /**
- * Return a non-const version of lh_entry->k.
- * k is const to indicate and help ensure that linkhash itself doesn't modify
+ * Return a non-const version of lh_entry.k.
+ *
+ * lh_entry.k is const to indicate and help ensure that linkhash itself doesn't modify
  * it, but callers are allowed to do what they want with it.
- * See also lh_entry->k_is_constant
+ * See also lh_entry.k_is_constant
  */
 #define lh_entry_k(entry) _LH_UNCONST((entry)->k)
 
 /**
- * Return a non-const version of lh_entry->v.
+ * Return a non-const version of lh_entry.v.
+ *
  * v is const to indicate and help ensure that linkhash itself doesn't modify
  * it, but callers are allowed to do what they want with it.
  */