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

Doxyfile

@@ -1935,7 +1935,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -1943,7 +1943,7 @@ MACRO_EXPANSION        = NO
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES the includes files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -1975,7 +1975,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = THIS_FUNCTION_IS_DEPRECATED(f)=f
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

json_object.h

@@ -161,6 +161,10 @@ typedef struct lh_table lh_table;
 typedef struct array_list array_list;
 
 typedef int json_bool;
+
+/**
+ * @brief The core type for all type of JSON objects handled by json-c
+ */
 typedef struct json_object json_object;
 
 /**
@@ -573,7 +577,7 @@ JSON_EXPORT size_t json_object_array_length(const struct json_object *obj);
 /** Sorts the elements of jso of type json_type_array
 *
 * Pointers to the json_object pointers will be passed as the two arguments
-* to @sort_fn
+* to sort_fn
 *
 * @param jso the json_object instance
 * @param sort_fn a sorting function
@@ -1017,6 +1021,9 @@ json_c_shallow_copy_fn json_c_shallow_copy_default;
  * @param src source JSON object whose contents will be copied
  * @param dst pointer to the destination object where the contents of `src`;
  *            make sure this pointer is initialized to NULL
+ * @param shallow_copy an optional function to copy individual objects, needed
+ *                     when custom serializers are in use.  See also
+ *                     json_object set_serializer.
  *
  * @returns 0 if the copy went well, -1 if an error occured during copy
  *          or if the destination pointer is non-NULL

json_util.h

@@ -75,6 +75,8 @@ extern int json_object_to_file_ext(const char *filename, struct json_object *obj
  * Handles partial writes and will keep writing until done, or an error
  * occurs.
  *
+ * @param fd an open, writable file descriptor to write to
+ * @param obj the object to serializer and write
  * @param flags flags to pass to json_object_to_json_string_ext()
  * @return -1 if something fails.  See json_util_get_last_err() for details.
  */

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
+ * Convenience function to create a new linkhash table with char keys.
- * 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
+ * Convenience function to create a new linkhash table with ptr keys.
- * 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
+ * Insert a record into the table using a precalculated key hash.
- * 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
+ * The hash h, which should be calculated with lh_get_hash() on k, is provided by
- * in the hash to all utility functions. Depending on use case, this can be a
+ *  the caller, to allow for optimization when multiple operations with the same
- * very considerate performance improvement.
+ *  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
+ * Lookup a record in the table using a precalculated key hash.
- * 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
+ * The hash h, which should be calculated with lh_get_hash() on k, is provided by
- * in the hash to all utility functions. Depending on use case, this can be a
+ *  the caller, to allow for optimization when multiple operations with the same
- * very considerate performance improvement.
+ *  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.
+ * Return a non-const version of lh_entry.k.
- * k is const to indicate and help ensure that linkhash itself doesn't modify
+ *
+ * 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.
  */