Add a brief overview of each file to the docs.

diff --git a/arraylist.h b/arraylist.h
index bc10903dcc98978d8c5536f3028c5bef818dd4c2..2cac236d94a7a16a120f59635c1d481df1143b7b 100644 (file)
--- 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 d14a1db0d7dc4b8144e73febd432c361f58973e2..14c1c132d37470d054f54db48617ed4a03108dcf 100644 (file)
--- 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 80ca3e43042e07c7e19111a2156378e5d76ec2a2..07fcc380b3c671aa60619a7f0b4b02f1ae66860d 100644 (file)
--- 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 dca0df5ca1a2975a10ccccf5e77c26410a624808..fc2daddee290d63a8130102798b579a2d5f468b3 100644 (file)
--- 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 d77f1a748d20d3b7c227fab0a1983af764bb5052..442174f6eb07f6b9dc06de957e3a3443c07b8e07 100644 (file)
--- 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 e86f4ccf88459151dee4708c472da39087bd8b14..3854913fc58ae7a1b864523fc3cb873c119fc918 100644 (file)
--- 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 3141a42923d7b36b4d4673b1d4a0e64c8f037b3b..f987d59f0743ee61318ddf04b592c444199075d6 100644 (file)
--- 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 0abbca21d86a3b450b834b0b4a3f43f1ce743363..53be70db089838bf3b0029c5e224596307ba22cf 100644 (file)
--- 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 49e9c2985e86825d25f9b90992a4354f7bb26491..b8746c0c9707f57f703a8ddccd102cb04c0ab46e 100644 (file)
--- 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 0ae4489922ab949733d6e8076934cb4d791a52f2..ed272b673dfd8c0215b7f34da509d860a60d7e0f 100644 (file)
--- 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 8f9fe8b8086d5abb9e7cb7c03a61ef9203abb658..571c084a68ac55e698674a96fef96dfd0520024f 100644 (file)
--- 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 2bb5821154518ef7b14b884ee3f3604d543b51ab..b147d99ebc84662c75d2f878f778e090d7714a7a 100644 (file)
--- 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 06047e27bc28716b6385dcde444586a275aff49e..552dbf8edbb7039b808a13cb7cb53fc45d827497 100644 (file)
--- 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 baf3eb90efa0295172971d86b1d5d018393e3d93..d530537b94f929405a6113c51bb376ad686fe2d6 100644 (file)
--- 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 68ac949e177cd5411957b9d17387f9b21ca55810..399cb072d7cbd27f8100d20a6c63eaeeaedcd0fc 100644 (file)
--- 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 7362d67d9cd5431ca95fdfb361aef9af0b79b84e..2f43dad1f35fba15d1c4fc5ba487cffd6866e828 100644 (file)
--- 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 7323aaa623ca2085e75f7f352d268691f3d0ed7f..8ca9b31c6f7c649b995f9b1351b8bf174e7c242a 100644 (file)
--- 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 51af81ec20f518547d241cce315eb8d5745f30ca..9c523596e36a1f2348841006e77ff46a04b7fabb 100644 (file)
--- 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 5c087f3d2c76e080f7f3156260205369707d9146..567438180439c69c0d04aca9d31e629b862253e0 100644 (file)
--- 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 <errno.h>
 

diff --git a/strerror_override_private.h b/strerror_override_private.h
index c7db84ced0de650e05cb15823eefcf0c2c31b864..5180b4f30764dff5fab0258b6ca603c5ea4867a4 100644 (file)
--- 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 40ff550f881e8a97907ee254cdd71af25fe2cbcb..43dbf8939c1df06ad0d2f64313826bce73fd28e7 100644 (file)
--- 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)