diff --git a/arraylist.h b/arraylist.h
index bc10903..2cac236 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 d14a1db..14c1c13 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 80ca3e4..07fcc38 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 dca0df5..fc2dadd 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 d77f1a7..442174f 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 e86f4cc..3854913 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 3141a42..f987d59 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 0abbca2..53be70d 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 49e9c29..b8746c0 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 0ae4489..ed272b6 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 8f9fe8b..571c084 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 2bb5821..b147d99 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 06047e2..552dbf8 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 baf3eb9..d530537 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 68ac949..399cb07 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 7362d67..2f43dad 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 7323aaa..8ca9b31 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 51af81e..9c52359 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 5c087f3..5674381 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 <errno.h>
 
diff --git a/strerror_override_private.h b/strerror_override_private.h
index c7db84c..5180b4f 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 40ff550..43dbf89 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)