From: Eric Haszlakiewicz Date: Wed, 6 Dec 2017 05:20:59 +0000 (-0500) Subject: Add a brief overview of each file to the docs. X-Git-Tag: json-c-0.13-20171207~8 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f2f103b98663d63ff8a9f60b2e1432f78463f486;p=thirdparty%2Fjson-c.git Add a brief overview of each file to the docs. --- diff --git a/arraylist.h b/arraylist.h index bc10903d..2cac236d 100644 --- a/arraylist.h +++ b/arraylist.h @@ -9,6 +9,12 @@ * */ +/** + * @file + * @brief Internal methods for working with json_type_array objects. + * Although this is exposed by the json_object_get_array() method, + * it is not recommended for direct use. + */ #ifndef _arraylist_h_ #define _arraylist_h_ diff --git a/bits.h b/bits.h index d14a1db0..14c1c132 100644 --- a/bits.h +++ b/bits.h @@ -1,5 +1,6 @@ /** * @file + * @brief Do not use, only contains deprecated defines. * @deprecated Use json_util.h instead. * * $Id: bits.h,v 1.10 2006/01/30 23:07:57 mclark Exp $ diff --git a/debug.h b/debug.h index 80ca3e43..07fcc380 100644 --- a/debug.h +++ b/debug.h @@ -10,6 +10,10 @@ * */ +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ #ifndef _DEBUG_H_ #define _DEBUG_H_ diff --git a/json.h b/json.h index dca0df5c..fc2dadde 100644 --- a/json.h +++ b/json.h @@ -10,6 +10,10 @@ * */ +/** + * @file + * @brief A convenience header that may be included instead of other individual ones. + */ #ifndef _json_h_ #define _json_h_ diff --git a/json_c_version.h b/json_c_version.h index d77f1a74..442174f6 100644 --- a/json_c_version.h +++ b/json_c_version.h @@ -5,6 +5,10 @@ * it under the terms of the MIT license. See COPYING for details. */ +/** + * @file + * @brief Methods for retrieving the json-c version. + */ #ifndef _json_c_version_h_ #define _json_c_version_h_ @@ -16,7 +20,21 @@ JSON_C_MICRO_VERSION) #define JSON_C_VERSION "0.12.99" +/** + * @see JSON_C_VERSION + * @return the version of the json-c library as a string + */ const char *json_c_version(void); /* Returns JSON_C_VERSION */ + +/** + * The json-c version encoded into an int, with the low order 8 bits + * being the micro version, the next higher 8 bits being the minor version + * and the next higher 8 bits being the major version. + * For example, 7.12.99 would be 0x00070B63. + * + * @see JSON_C_VERSION_NUM + * @return the version of the json-c library as an int + */ int json_c_version_num(void); /* Returns JSON_C_VERSION_NUM */ #endif diff --git a/json_inttypes.h b/json_inttypes.h index e86f4ccf..3854913f 100644 --- a/json_inttypes.h +++ b/json_inttypes.h @@ -1,4 +1,8 @@ +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ #ifndef _json_inttypes_h_ #define _json_inttypes_h_ diff --git a/json_object.h b/json_object.h index 3141a429..f987d59f 100644 --- a/json_object.h +++ b/json_object.h @@ -10,6 +10,10 @@ * */ +/** + * @file + * @brief Core json-c API. Start here, or with json_tokener.h + */ #ifndef _json_object_h_ #define _json_object_h_ diff --git a/json_object_private.h b/json_object_private.h index 0abbca21..53be70db 100644 --- a/json_object_private.h +++ b/json_object_private.h @@ -9,6 +9,10 @@ * */ +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ #ifndef _json_object_private_h_ #define _json_object_private_h_ diff --git a/json_pointer.h b/json_pointer.h index 49e9c298..b8746c0c 100644 --- a/json_pointer.h +++ b/json_pointer.h @@ -6,6 +6,11 @@ * */ +/** + * @file + * @brief JSON Pointer (RFC 6901) implementation for retrieving + * objects from a json-c object tree. + */ #ifndef _json_pointer_h_ #define _json_pointer_h_ diff --git a/json_tokener.h b/json_tokener.h index 0ae44899..ed272b67 100644 --- a/json_tokener.h +++ b/json_tokener.h @@ -9,6 +9,10 @@ * */ +/** + * @file + * @brief Methods to parse an input string into a tree of json_object objects. + */ #ifndef _json_tokener_h_ #define _json_tokener_h_ diff --git a/json_util.h b/json_util.h index 8f9fe8b8..571c084a 100644 --- a/json_util.h +++ b/json_util.h @@ -9,6 +9,10 @@ * */ +/** + * @file + * @brief Miscllaneous utility functions and macros. + */ #ifndef _json_util_h_ #define _json_util_h_ diff --git a/json_visit.h b/json_visit.h index 2bb58211..b147d99e 100644 --- a/json_visit.h +++ b/json_visit.h @@ -2,6 +2,10 @@ #ifndef _json_c_json_visit_h_ #define _json_c_json_visit_h_ +/** + * @file + * @brief Methods for walking a tree of objects. + */ #include "json_object.h" typedef int (json_c_visit_userfunc)(json_object *jso, int flags, diff --git a/linkhash.h b/linkhash.h index 06047e27..552dbf8e 100644 --- a/linkhash.h +++ b/linkhash.h @@ -10,6 +10,12 @@ * */ +/** + * @file + * @brief Internal methods for working with json_type_object objects. Although + * this is exposed by the json_object_get_object() function and within the + * json_object_iter type, it is not recommended for direct use. + */ #ifndef _linkhash_h_ #define _linkhash_h_ diff --git a/math_compat.h b/math_compat.h index baf3eb90..d530537b 100644 --- a/math_compat.h +++ b/math_compat.h @@ -1,6 +1,11 @@ #ifndef __math_compat_h #define __math_compat_h +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ + /* Define isnan, isinf, infinity and nan on Windows/MSVC */ #ifndef HAVE_DECL_ISNAN diff --git a/printbuf.h b/printbuf.h index 68ac949e..399cb072 100644 --- a/printbuf.h +++ b/printbuf.h @@ -13,6 +13,13 @@ * (http://www.opensource.org/licenses/mit-license.php) */ +/** + * @file + * @brief Internal string buffer handing. Unless you're writing a + * json_object_to_json_string_fn implementation for use with + * json_object_set_serializer() direct use of this is not + * recommended. + */ #ifndef _printbuf_h_ #define _printbuf_h_ diff --git a/random_seed.h b/random_seed.h index 7362d67d..2f43dad1 100644 --- a/random_seed.h +++ b/random_seed.h @@ -9,6 +9,10 @@ * */ +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ #ifndef seed_h #define seed_h diff --git a/snprintf_compat.h b/snprintf_compat.h index 7323aaa6..8ca9b31c 100644 --- a/snprintf_compat.h +++ b/snprintf_compat.h @@ -1,6 +1,11 @@ #ifndef __snprintf_compat_h #define __snprintf_compat_h +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ + /* * Microsoft's _vsnprintf and _snprint don't always terminate * the string, so use wrappers that ensure that. diff --git a/strdup_compat.h b/strdup_compat.h index 51af81ec..9c523596 100644 --- a/strdup_compat.h +++ b/strdup_compat.h @@ -1,6 +1,11 @@ #ifndef __strdup_compat_h #define __strdup_compat_h +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ + #if !defined(HAVE_STRDUP) && defined(_MSC_VER) /* MSC has the version as _strdup */ # define strdup _strdup diff --git a/strerror_override.h b/strerror_override.h index 5c087f3d..56743818 100644 --- a/strerror_override.h +++ b/strerror_override.h @@ -1,6 +1,11 @@ #ifndef _json_strerror_override_h_ #define _json_strerror_override_h_ +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ + #include "config.h" #include diff --git a/strerror_override_private.h b/strerror_override_private.h index c7db84ce..5180b4f3 100644 --- a/strerror_override_private.h +++ b/strerror_override_private.h @@ -1,6 +1,11 @@ #ifndef __json_strerror_override_private_h__ #define __json_strerror_override_private_h__ +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ + /* Used by tests to get consistent output */ extern int _json_c_strerror_enable; diff --git a/vasprintf_compat.h b/vasprintf_compat.h index 40ff550f..43dbf893 100644 --- a/vasprintf_compat.h +++ b/vasprintf_compat.h @@ -1,6 +1,11 @@ #ifndef __vasprintf_compat_h #define __vasprintf_compat_h +/** + * @file + * @brief Do not use, json-c internal, may be changed or removed at any time. + */ + #include "snprintf_compat.h" #if !defined(HAVE_VASPRINTF)