From: Eric Haszlakiewicz Date: Thu, 7 Dec 2017 04:53:12 +0000 (-0500) Subject: Squash doxygen warnings, and make a few slight improvements to the docs. X-Git-Tag: json-c-0.13-20171207~6 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=8c82f0e5c31e90e958a9cbbd7b5ea8e1e4f5e493;p=json-c Squash doxygen warnings, and make a few slight improvements to the docs. --- diff --git a/Doxyfile b/Doxyfile index 49b072f..31e9025 100644 --- a/Doxyfile +++ b/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 diff --git a/json_object.h b/json_object.h index f987d59..9d79859 100644 --- a/json_object.h +++ b/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 diff --git a/json_util.h b/json_util.h index 571c084..e065f60 100644 --- a/json_util.h +++ b/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. */ 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. */