diff --git a/src/getdns/getdns.h.in b/src/getdns/getdns.h.in
index f7825361..5851c023 100644
--- a/src/getdns/getdns.h.in
+++ b/src/getdns/getdns.h.in
@@ -501,6 +501,8 @@ typedef enum getdns_data_type
 {
 	t_dict, t_list, t_int, t_bindata
 } getdns_data_type;
+
+
 typedef struct getdns_bindata
 {
 	size_t size;
@@ -709,12 +711,46 @@ getdns_return_t getdns_dict_get_int(const getdns_dict *dict,
  * @return pointer to an allocated list, NULL if insufficient memory
  */
 getdns_list *getdns_list_create();
+
+/**
+ * create a new list with no items, creating and initializing it with the
+ * custom memory function from context.  These memory functions will be used
+ * for creating, and inherited by the list members when populating the list.
+ * The custom deallocator will be used for destroying the list.
+ * @param context The context from which the custom memory functions will be
+ *                used to create and initialize the list.
+ * @return pointer to an allocated list, NULL if insufficient memory
+ */
 getdns_list *getdns_list_create_with_context(getdns_context *context);
+
+/**
+ * create a new list with no items, creating and initializing it with the
+ * provided custom memory function.  These memory functions will be used
+ * for creating, and inherited by the list members when populating the list.
+ * The custom deallocator will be used for destroying the list.
+ * @param malloc Custom allocator
+ * @param realloc Custom reallocator
+ * @param free Custom deallocator
+ * @return pointer to an allocated list, NULL if insufficient memory
+ */
 getdns_list *getdns_list_create_with_memory_functions(
     void *(*malloc) (size_t),
     void *(*realloc) (void *, size_t),
     void (*free) (void *)
 );
+
+/**
+ * create a new list with no items, creating and initializing it with the
+ * provided extended custom memory function.  These memory functions will be
+ * used for creating, and inherited by the list members when populating the
+ * list.  The custom deallocator will be used for destroying the list.
+ * @param userarg Will be passed as the first argument to the extended 
+ *                custom malloc, realloc, and free.
+ * @param malloc Custom allocator
+ * @param realloc Custom reallocator
+ * @param free Custom deallocator
+ * @return pointer to an allocated list, NULL if insufficient memory
+ */
 getdns_list *getdns_list_create_with_extended_memory_functions(
     void *userarg,
     void *(*malloc) (void *userarg, size_t),
@@ -795,12 +831,46 @@ getdns_return_t getdns_list_set_int(getdns_list *list, size_t index,
  * @return pointer to an allocated dictionary, NULL if insufficient memory
  */
 getdns_dict *getdns_dict_create();
+
+/**
+ * create a new dict with no items, creating and initializing it with the
+ * custom memory function from context.  These memory functions will be used
+ * for creating, and inherited by the list members when populating the dict.
+ * The custom deallocator will be used for destroying the dict.
+ * @param context The context from which the custom memory functions will be
+ *                used to create and initialize the dict.
+ * @return pointer to an allocated dict, NULL if insufficient memory
+ */
 getdns_dict *getdns_dict_create_with_context(getdns_context *context);
+
+/**
+ * create a new dict with no items, creating and initializing it with the
+ * provided custom memory function.  These memory functions will be used
+ * for creating, and inherited by the dict members when populating the dict.
+ * The custom deallocator will be used for destroying the dict.
+ * @param malloc Custom allocator
+ * @param realloc Custom reallocator
+ * @param free Custom deallocator
+ * @return pointer to an allocated dict, NULL if insufficient memory
+ */
 getdns_dict *getdns_dict_create_with_memory_functions(
     void *(*malloc) (size_t),
     void *(*realloc) (void *, size_t),
     void (*free) (void *)
 );
+
+/**
+ * create a new dict with no items, creating and initializing it with the
+ * provided extended custom memory function.  These memory functions will be
+ * used for creating, and inherited by the dict members when populating the
+ * dict.  The custom deallocator will be used for destroying the dict.
+ * @param userarg Will be passed as the first argument to the extended 
+ *                custom malloc, realloc, and free.
+ * @param malloc Custom allocator
+ * @param realloc Custom reallocator
+ * @param free Custom deallocator
+ * @return pointer to an allocated dict, NULL if insufficient memory
+ */
 getdns_dict *getdns_dict_create_with_extended_memory_functions(
     void *userarg,
     void *(*malloc) (void *userarg, size_t),
@@ -872,7 +942,10 @@ getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);
 /**
  * \addtogroup callbackfns getdns_callback functions
  */
-/* Callback arguments */
+/**
+ * The type of the callback function that must be registered when scheduling
+ * asynchronous requests.
+ */
 typedef void (*getdns_callback_t) (getdns_context *context,
     getdns_callback_type_t callback_type,
     getdns_dict * response,
@@ -1019,6 +1092,10 @@ getdns_context_create_with_extended_memory_functions(
     void (*free) (void *userarg, void *)
 );
 
+/**
+ * destroy the context.  All outstanding requests will be cancelled with
+ * the getdns_cancel_callback() function.
+ */
 void getdns_context_destroy(getdns_context *context);
 /** @}
  */
@@ -1028,6 +1105,11 @@ void getdns_context_destroy(getdns_context *context);
  * \addtogroup callbackfns getdns_callback functions
  * @{
  */
+/**
+ * Cancel an outstanding asynchronous request.  The callback registered with
+ * the request will be called with the getdns_callback_type_t set to
+ * GETDNS_CALLBACK_CANCEL and the response set to NULL.
+ */
 getdns_return_t
 getdns_cancel_callback(getdns_context *context,
     getdns_transaction_t transaction_id);
@@ -1111,6 +1193,10 @@ getdns_service_sync(getdns_context *context,
  * @{
  */
 
+/**
+ * Convert a domain name in DNS wire format to presentation format.
+ * The newly allocated string should be freed with free.
+ */
 getdns_return_t
 getdns_convert_dns_name_to_fqdn(
     const getdns_bindata *dns_name_wire_fmt,