mirror/json-c
1
0
Fork 0
mirror of https://github.com/json-c/json-c.git synced 2026-03-24 15:39:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Eric Haszlakiewicz
2017-12-06 23:53:12 -05:00
parent 219025727d
commit 8c82f0e5c3
4 changed files with 64 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
Doxyfile
View File

@@ -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

9
json_object.h
View File

@@ -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

2
json_util.h
View File

@@ -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.
*/

78
linkhash.h
View File

@@ -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.
*/