Add a brief overview of each file to the docs.

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_
 

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 $

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_
 

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_
 

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

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_
 

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_
 

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_
 

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_
 

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_
 

json_util.h

@@ -9,6 +9,10 @@
  *
  */
 
+/**
+ * @file
+ * @brief Miscllaneous utility functions and macros.
+ */ 
 #ifndef _json_util_h_
 #define _json_util_h_
 

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,

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_
 

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

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_
 

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
 

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.

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

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>
 

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;
 

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)