Merge pull request #283 from wtoorop/devel/doxygen

Devel/doxygen

ChangeLog

@@ -1,4 +1,5 @@
 * 2017-04-??: Version 1.1.0
+  * Spelling fixes.  Thanks Andreas Schulze.
   * bugfix: Reschedule request timeout when getting the DNSSEC chain.
   * getdns_context_unset_edns_maximum_udp_payload_size() to reset
     to default IPv4/IPv6 dependent edns max udp payload size.
@@ -176,7 +177,7 @@
     '-1' to append suffix only to single label after failure
     '-M' to append suffix only to multi label name after failure
     '-N' to never append a suffix
-    '-Z <suffixes>' to set suffixes with the given comma separed list
+    '-Z <suffixes>' to set suffixes with the given comma separated list
   * Better help text for getdns_query (printed with the '-h' option)
   * Setting the +specify_class extension with getdns_query
   * Return NOT_IMPLEMENTED for not implemented namespaces, and the

doc/getdns_address.3.in

@@ -33,7 +33,7 @@
 -- get ip address(es) for a name
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_cancel_callback.3.in

@@ -32,7 +32,7 @@
 -- cancel an outstanding asyn getdns request
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_context.3.in

@@ -39,7 +39,7 @@
 .ad n
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>
@@ -141,7 +141,7 @@ in use might have a requirements on this issue. You may need to provide one or
 two functions to allow it to function properly. For example before you call 
 getdns_context_create() you may need to use 
 the openssl functions CRYPTO_set_id_callback and CRYPTO_set_locking_callback to set up
-asyncronous operation (the  application calls these functions once for initialisation).  
+asynchronous operation (the  application calls these functions once for initialisation).
 Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function.
 
 .HP 3

doc/getdns_context_set.3.in

@@ -45,7 +45,7 @@
 .ad n
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_context_set_context_update_callback.3.in

@@ -32,7 +32,7 @@
 -- get informed on getdns context updates
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_convert.3.in

@@ -34,7 +34,7 @@
 -- convert dname between presentation- and wire-format
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_dict.3.in

@@ -38,7 +38,7 @@
 .ad n
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_dict_get.3.in

@@ -38,7 +38,7 @@
 -- get value by name from a getdns dict
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_dict_set.3.in

@@ -36,7 +36,7 @@
 -- set a value by name in a getdns dict
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_display_ip_address.3.in

@@ -32,7 +32,7 @@
 -- convert an getdns ip address to string
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_general.3.in

@@ -33,7 +33,7 @@
 -- do a getdns DNS lookup
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_hostname.3.in

@@ -33,7 +33,7 @@
 -- get hostname by address
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_list.3.in

@@ -38,7 +38,7 @@
 .ad n
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_list_get.3.in

@@ -38,7 +38,7 @@
 -- get a value by index from a getdns list
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_list_set.3.in

@@ -36,7 +36,7 @@
 -- set a value by index from a getdns list
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_pretty_print_dict.3.in

@@ -32,7 +32,7 @@
 -- return a string representation of a getdns dict
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_root_trust_anchor.3.in

@@ -32,7 +32,7 @@
 -- return the getdns list of default root trust anchors
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_service.3.in

@@ -33,7 +33,7 @@
 -- getdns lookup of a service
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/getdns_validate_dnssec.3.in

@@ -32,7 +32,7 @@
 -- DNSSEC validate a given getdns record
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 #include <getdns.h>

doc/libgetdns.3.in

@@ -32,7 +32,7 @@ libgetdns
 -- an implementation of a modern asynchronous DNS API by and for application developers
 
 .SH LIBRARY
-DNS Resolver library (libgetdns, -lgetdns)
+DNS Resolver library (libgetdns, \-lgetdns)
 
 .SH SYNOPSIS
 .B libgetdns
@@ -230,7 +230,7 @@ Set to GETDNS_EXTENSION_TRUE to include the DNSSEC status for each DNS record in
 .HP 3
 "dnssec_return_only_secure" (int)
 
-Set to GETDNS_EXTENSION_TRUE to cause only records that the API can validate as secure withe DNSSEC to be returned in the
+Set to GETDNS_EXTENSION_TRUE to cause only records that the API can validate as secure with DNSSEC to be returned in the
 .I replies_tree
 and
 .I replies_full lists

src/getdns/getdns.h.in

@@ -490,17 +490,40 @@ typedef enum getdns_callback_type_t {
  */
 
 
+/**
+ * Many calls in the DNS API require a DNS context. A DNS context contains
+ * the information that the API needs in order to process DNS calls, such
+ * as the locations of upstream DNS servers, DNSSEC trust anchors, and so on.
+ * The internal structure of the DNS context is opaque, and might be different
+ * on each OS. When a context is passed to any function, it must be an
+ * allocated context; the context must not be NULL.
+ *
+ * Use getdns_context_set_* functions to configure a context.
+ */
 typedef struct getdns_context getdns_context;
+
+/**
+ * When scheduling asynchronous requests, transaction identifiers associated
+ * with the request are returned.  These identifiers are of the type:
+ * getdns_transaction_t.  These identifiers can be used to associate answers
+ * with requests, and also to cancel outstanding requests.
+ */
 typedef uint64_t getdns_transaction_t;
 
 
 /**
- * used to check data types within complex types (dict, list)
+ * getdns_list_get_data_type() and getdns_dict_get_data_type() return the type
+ * of data on an index in a getdns_list, or on a name in a getdns_dict.
  */
 typedef enum getdns_data_type
 {
 	t_dict, t_list, t_int, t_bindata
 } getdns_data_type;
+
+
+/**
+ * A  struct to hold binary data.
+ */
 typedef struct getdns_bindata
 {
 	size_t size;
@@ -709,12 +732,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 +852,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),
@@ -823,8 +914,17 @@ void getdns_dict_destroy(getdns_dict *dict);
  * @{
  */
 
+/**
+ * create a new entry in the dictionary, or replace the value of an existing entry
+ * this routine makes a copy of the child_dict_
+ * @param dict dictionary in which to add or change the value
+ * @param name key that identifies which item in the dictionary to add/change
+ * @param child_dict value to assign to the node identified by name
+ * @return GETDNS_RETURN_GOOD on success
+ */
 getdns_return_t getdns_dict_set_dict(getdns_dict *dict,
     const char *name, const getdns_dict *child_dict);
+
 /**
  * create a new entry in the dictionary, or replace the value of an existing entry
  * this routine makes a copy of the child_list
@@ -872,7 +972,31 @@ 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.  The registered function will be called from the
+ * eventloop with the following parameters.
+ * @param context The DNS context that was used in the calling function
+ * @param callback_type Supplies the reason for the callback.
+ *                      This will be one of:
+ *                      - GETDNS_CALLBACK_COMPLETE The response has the
+ *                        requested data in it
+ *                      - GETDNS_CALLBACK_CANCEL The calling program cancelled
+ *                        the callback; response is NULL
+ *                      - GETDNS_CALLBACK_TIMEOUT The requested action timed
+ *                        out; response is filled in with empty structures or
+ *                        will contain additional information about the timeout
+ *                        when used in combination with the
+ *                        return_call_reporting extension.
+ *                      - GETDNS_CALLBACK_ERROR The requested action had an 
+ *                        error; response is NULL.
+ * @param response A response object with the response data. 
+ *                 The application is responsible for cleaning up the response
+ *                 object with getdns_dict_destroy.
+ * @param userarg Identical to the userarg passed to the calling function.
+ * @param transaction_id The transaction identifier that was assigned by the
+ *                       calling function.
+ */
 typedef void (*getdns_callback_t) (getdns_context *context,
     getdns_callback_type_t callback_type,
     getdns_dict * response,
@@ -1019,6 +1143,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 +1156,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,26 +1244,93 @@ 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.
+ * @param dns_name_wire_fmt A bindata to the DNS name in wire format
+ * @param fqdn_as_string A reference to a pointer that will be set
+ *                       to a newly allocated string containing the
+ *                       presentation format of the name.  The caller
+ *                       is responsible for deallocate this space with free().
+ * @return GETDNS_RETURN_GOOD on success or GETDNS_RETURN_GENERIC_ERROR
+ *         when the wireformat name could not be parsed.
+ */
 getdns_return_t
 getdns_convert_dns_name_to_fqdn(
     const getdns_bindata *dns_name_wire_fmt,
     char **fqdn_as_string);
 
+/**
+ * Convert a domain name in presentation format to DNS wire format.
+ * @param fqdn_as_string The name to convert in presentation format.
+ * @param dns_name_wire_fmt A reference to a pointer that will be set
+ *                          to a newly allocated bindata containing the
+ *                          DNS wire format of the name.  The caller
+ *                          is responsible for deallocate this space with free().
+ * @return GETDNS_RETURN_GOOD on success or GETDNS_RETURN_GENERIC_ERROR
+ *         when the presentation format name could not be parsed.
+ */
 getdns_return_t
 getdns_convert_fqdn_to_dns_name(
     const char *fqdn_as_string,
     getdns_bindata **dns_name_wire_fmt);
 
+/**
+ * Convert an Unicode encoded label to ASCII encoding following the
+ * rules for IDNA 2008 described in RFC 5890-5892.
+ * @param ulabel The Unicode encoded label to convert.
+ * @return The ASCII encoding label. The caller is responsible for deallocate
+ * this space with free().
+ */ 
 char *getdns_convert_ulabel_to_alabel(const char *ulabel);
 
+/**
+ * Convert an ASCII encoded label to Unicode encoding following the
+ * rules for IDNA 2008 described in RFC 5890-5892.
+ * @param alabel The ASCII encoded label to convert.
+ * @return The Unicode encoding label. The caller is responsible for
+ * deallocation with free().
+ */ 
 char *getdns_convert_alabel_to_ulabel(const char *alabel);
 
+/**
+ * Offline DNSSEC validate Resource Records with the help of support
+ * records and a DNSSEC trust anchor.
+ * @param to_validate This is a list of reply_dicts to validate (as can
+ *                    be seen under "replies_tree" in a response dict), or
+ *                    an RRset with signatures represented as a list of
+ *                    rr_dicts.  The format of rr_dict can be seen in
+ *                    the sections of reply_dicts in response dicts.
+ *                    It is also possible to validate the non-existance
+ *                    of a query.  Besides all the necessary NSEC(3)s plus
+ *                    signature, the to_validate should then also contain
+ *                    a question rr_dict with a qname, qclass and qtype.
+ * @param support_records A list of all the DNSKEY, DS and NSEC(3) RRsets
+ *                        (in the form of rr_dicts) that may be used to
+ *                        validate the RRsets or replies in to_validate.
+ *                        The value returned under "validation_chain" in a
+ *                        response dict when the dnssec_return_validation_chain
+ *                        extension was used, can be used directly for this.
+ * @param trust_anchors A list of rr_dicts containing the DNSSEC trust anchors.
+ *                      The return value of the getdns_root_trust_anchor()
+ *                      can be used directly for this.
+ * @return The function returns one of GETDNS_DNSSEC_SECURE,
+ * GETDNS_DNSSEC_BOGUS, GETDNS_DNSSEC_INDETERMINATE, or GETDNS_DNSSEC_INSECURE
+ * depending on the validation status.
+ */
 getdns_return_t
 getdns_validate_dnssec(getdns_list *to_validate,
     getdns_list *support_records,
     getdns_list *trust_anchors);
 
-/* Get root trust anchor */
+/**
+ * Get the default list of trust anchor records that is used by the library
+ * to validate DNSSEC.
+ * @param utc_date_of_anchor Set to the number of seconds since epoch
+ *                           the trust anchors were obtained
+ * @return The list of DNSSEC trust anchors, or NULL on error. The  caller is
+ * responsible for deallocating the list with getdns_list_destroy().
+ */
 getdns_list *getdns_root_trust_anchor(time_t *utc_date_of_anchor);
 
 /**
@@ -1141,6 +1341,13 @@ getdns_list *getdns_root_trust_anchor(time_t *utc_date_of_anchor);
  */
 char *getdns_pretty_print_dict(const getdns_dict *some_dict);
 
+/**
+ * Converts a getdns_bindata representing an IPv4 or IPv6 address to a 
+ * textual representation.
+ * @param bindata_of_ipv4_or_ipv6_address The IP address to convert.
+ * @return character array (caller must free this) containing the textual
+ * representation of the address.
+ */
 char *getdns_display_ip_address(const getdns_bindata
     *bindata_of_ipv4_or_ipv6_address);
 
@@ -1152,6 +1359,19 @@ char *getdns_display_ip_address(const getdns_bindata
  * \addtogroup context_set getdns_context_set functions
  * @{
  */
+
+/**
+ * An application can be notified when the context is changed.
+ * Note that this implementation has an extended version of this function
+ * in which an additional userarg parameter can be registered:
+ * #getdns_context_set_update_callback .
+ * @param context The context for which to monitor changes
+ * @param value The callback function that will be called when any context is
+ *              changed. A update callback function can be deregistered by
+ *              passing NULL.
+ * @return GETDNS_RETURN_GOOD when succesful.
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
+ */
 getdns_return_t
 getdns_context_set_context_update_callback(
   getdns_context *context,
@@ -1159,73 +1379,362 @@ getdns_context_set_context_update_callback(
                 getdns_context_code_t changed_item)
 );
 
+/**
+ * Specify whether DNS queries are performed with recursive lookups or as a
+ * stub resolver. The default value is GETDNS_RESOLUTION_RECURSING.
+ * @see getdns_context_get_resolution_type
+ * @param context The context to configure
+ * @param value GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown resolution types
+ * @return GETDNS_RETURN_NOT_IMPLEMENTED when getdns was compiled for stub
+ *         resolution only and recursing resolution type was requested.
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
+ */
 getdns_return_t
 getdns_context_set_resolution_type(getdns_context *context,
     getdns_resolution_t value);
 
+/**
+ * Sets the ordered list of namespaces that will be queried.
+ * This context setting is ignored for the getdns_general and
+ * getdns_general_sync functions; it is used for the other funtions. 
+ * When a normal lookup is done, the API does the lookups in the order given
+ * and stops when it gets the first result
+ * @see getdns_context_get_namespaces
+ * @param context The context to configure
+ * @param namespace_count The number of values in the namespaces list.
+ * @param namespaces An ordered list of namespaces that will be queried.
+ *                   The values are: GETDNS_NAMESPACE_DNS,
+ *                   GETDNS_NAMESPACE_LOCALNAMES, GETDNS_NAMESPACE_NETBIOS,
+ *                   GETDNS_NAMESPACE_MDNS, and GETDNS_NAMESPACE_NIS. 
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown namespace types
+ * @return GETDNS_RETURN_NOT_IMPLEMENTED when unsupported namespaces were
+ *         given.  Currently this implementation supports only
+ *         GETDNS_NAMESPACE_DNS, GETDNS_NAMESPACE_LOCALNAMES and has an
+ *         draft implementation of GETDNS_NAMESPACE_MDNS, which has to be
+ *         enabled at configure time.
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
+ */
 getdns_return_t
 getdns_context_set_namespaces(getdns_context *context,
     size_t namespace_count, getdns_namespace_t *namespaces);
 
+/**
+ * Specifies what transport are used for DNS lookups. The default is
+ * GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP. Use of this function
+ * is discouraged.  Please use #getdns_context_set_dns_transport_list()
+ * instead of this function.  
+ * @see getdns_context_get_dns_transport
+ * @see getdns_context_set_dns_transport_list
+ * @see getdns_context_get_dns_transport_list
+ * @param context The context to configure
+ * @param value The transport to use for DNS lookups.
+ *              The value is GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP,
+ *              GETDNS_TRANSPORT_UDP_ONLY, GETDNS_TRANSPORT_TCP_ONLY,
+ *              GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN,
+ *              GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN or
+ *              GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
+ */
 getdns_return_t
 getdns_context_set_dns_transport(getdns_context *context,
     getdns_transport_t value);
 
+/**
+ * Specifies what transport is used for DNS lookups. The default is a list
+ * containing GETDNS_TRANSPORT_UDP then GETDNS_TRANSPORT_TCP.  The API will
+ * return information on the actual transport used to fulfill the request in
+ * the response dict, when the return_call_reporting extension is used.
+ * @see getdns_context_get_dns_transport_list
+ * @see getdns_context_set_dns_transport
+ * @see getdns_context_get_dns_transport
+ * @param context The context to configure
+ * @param transport_count The number of values in the transports list.
+ * @param transports An ordered list of transports that will be used for DNS
+ *                   lookups. If only one transport value is specified it will
+ *                   be the only transport used. Should it not be available
+ *                   basic resolution will fail. Fallback transport options are
+ *                   specified by including multiple values in the list.
+ *                   The values are: GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP,
+ *                   or GETDNS_TRANSPORT_TLS
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
+ */
 getdns_return_t
 getdns_context_set_dns_transport_list(getdns_context *context,
     size_t transport_count, getdns_transport_list_t *transports);
 
+/**
+ * Specify number of milliseconds the API will leave an idle TCP or TLS
+ * connection open for (idle means no outstanding responses and no pending
+ * queries).  When set to 0, all currently open idle connections will be
+ * closed immediately.  The default is 0.
+ * Note with synchronous queries, idle connections can not reliably be timed.
+ * Each new synchronous request, will reset the counter no matter the time
+ * in between requests, and thus leave the connection open always.  This
+ * setting is thus only meaningful when doing requests asynchronously.
+ * @see getdns_context_get_idle_timeout
+ * @param context The context to configure
+ * @param timeout The number of milliseconds the API will leave an idle TCP
+ *                or TLS connection open for
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
+ */
 getdns_return_t
 getdns_context_set_idle_timeout(getdns_context *context, uint64_t timeout);
 
+/**
+ * Limit the number of outstanding DNS queries. When more than limit requests
+ * are scheduled, they are kept on an internal queue, to be rescheduled when
+ * the number of outstanding queries drops below the limit again.
+ * A value of 0 indicates that the number of outstanding DNS queries is
+ * unlimited, however, queries will be put on the internal queue too when
+ * system resources are exhausted (i.e. number of available sockets).
+ * The default value is 0.
+ * @see getdns_context_get_limit_outstanding_queries
+ * @param context The context to configure
+ * @param limit The maximum number of outstanding DNS queries.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
+ */
 getdns_return_t
 getdns_context_set_limit_outstanding_queries(getdns_context *context,
     uint16_t limit);
 
+/**
+ * Specifies number of milliseconds the API will wait for request to return.
+ * The default is 5000 (i.e. 5 seconds).
+ * @see getdns_context_get_timeout
+ * @param context The context to configure
+ * @param timeout The number of milliseconds the API will wait for request to
+ *                return.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER for a timeout 0,
+ *         or when context was NULL
+ */
 getdns_return_t
 getdns_context_set_timeout(getdns_context *context, uint64_t timeout);
 
+/**
+ * Specifies whether or not DNS queries follow redirects.
+ * The default value is GETDNS_REDIRECTS_FOLLOW.
+ * In this implementation, redirects are only actively followed in the recursing
+ * resolution mode.  The GETDNS_REDIRECTS_DO_NOT_FOLLOW will not prevent this,
+ * but the response will be stripped of all resource records that could only be
+ * found through following redirects.  The setting will do this with answers
+ * provided by an upstream in stub resolution mode too.
+ * @see getdns_context_get_follow_redirects
+ * @param context The context to configure
+ * @param value GETDNS_REDIRECTS_FOLLOW for normal following of redirects
+ *              through CNAME and DNAME; or GETDNS_REDIRECTS_DO_NOT_FOLLOW to
+ *              cause any lookups that would have gone through CNAME and DNAME
+ *              to return the CNAME or DNAME, not the eventual target.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER for an unknown value,
+ *         or when context was NULL
+ */
 getdns_return_t
 getdns_context_set_follow_redirects(getdns_context *context,
     getdns_redirects_t value);
 
+/**
+ * Configure the list of addresses to be used for looking up top-level domains.
+ * The default is the list of "normal" IANA root servers
+ * @see getdns_context_get_dns_root_servers
+ * @param context The context to configure
+ * @param addresses The list contains dicts that are addresses to be used for
+ *                  looking up top-level domains. Each dict in the list
+ *                  contains at least two names: address_type (whose value is
+ *                  a bindata; it is currently either "IPv4" or "IPv6") and
+ *                  address_data (whose value is a bindata).
+ *                  This implementation also accepts a list of addressxi
+ *                  bindatas. Or a list of rr_dicts for address records (i.e.
+ *                  the additional section of a NS query for ".", or a with
+ *                  getdns_fp2rr_list() converted root.hints file).
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL when there were problems
+ *         parsing the provided addresses list.
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_dns_root_servers(getdns_context *context,
     getdns_list *addresses);
 
+/**
+ * Specifies whether, how and when to append a suffix to the query string.
+ * The non-standard implementation default is
+ * GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST.
+ * @see getdns_context_get_append_name
+ * @param context The context to configure
+ * @param value GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST,
+ *              GETDNS_APPEND_NAME_ALWAYS,
+ *              GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,
+ *              GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE,
+ *              or GETDNS_APPEND_NAME_NEVER.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values.
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_append_name(getdns_context *context,
     getdns_append_name_t value);
 
+/**
+ * Specify the list of suffixes to be appended based on the value off the 
+ * append_name setting.  The default is read from OS, or an empty list when
+ * the context is not initialized with OS defaults.
+ * @see getdns_context_get_suffix
+ * @param context The context to configure
+ * @param value A list of bindatas that are strings that are to be appended
+ *              based on the value off the append_name setting.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values.
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_suffix(getdns_context *context, getdns_list *value);
 
+/**
+ * Specify the DNSSEC trust anchors.  The default is to read it from 
+ * @TRUST_ANCHOR_FILE@.
+ * @see getdns_context_get_dnssec_trust_anchors
+ * @param context The context to configure
+ * @param value A list of rr_dicts for DS or DNSKEY that are the DNSSEC
+ *              trust anchors.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values.
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_dnssec_trust_anchors(getdns_context *context,
     getdns_list *value);
 
+/**
+ * Specify the DNSSEC allowed skew.  The default is 0.
+ * @see getdns_context_get_dnssec_allowed_skew
+ * @param context The context to configure
+ * @param value The number of seconds of skew that is allowed in either
+ *              direction when checking an RRSIG's Expiration and Inception
+ *              fields.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_dnssec_allowed_skew(getdns_context *context,
     uint32_t value);
 
+
+/**
+ * Specify where a stub resolver will send queries.  The default value is set
+ * from the OS when the context is created with the set_from_os flag, or
+ * empty otherwise.
+ * @see getdns_context_get_upstream_recursive_servers
+ * @param context The context to configure
+ * @param upstream_list The upstreams are specified either by a getdns_bindata
+ *                      containing a IPv4 or IPv6 address in network format
+ *                      or a `getdns_dict`, containing at least a name
+ *                      `address_data` whose value is the address bindata, and
+ *                      optionally also:
+ *                      - `scode_id` containing an getdns_bindata with the
+ *                        scope ID for IPv6 link-local addresses.
+ *                      - `port` an integer specifying which port to use to
+ *                        contact this upstream over UDP and TCP;
+ *                        the default is 53
+ *                      - `tsig_algorithm` (a bindata) that is the name of the
+ *                        TSIG hash algorithm 
+ *                      - `tsig_name` (a bindata) that is the name of the TSIG key
+ *                      - `tsig_secret` (a bindata) that is the TSIG key
+ *                      - `tls_port` (a integer) that is the port to use to
+ *                        contact this upstream over TLS
+ *                      - `tls_auth_name` (a bindata) that is the name of the
+ *                        upstream (as a bindata containing a string) which
+ *                        must be verified to confirm its identity.
+ *                      - `tls_pubkey_pinset` (a list) containing dicts with
+ *                        - `digest` which must be a bindata containing the
+ *                          text sha256
+ *                        - `value` A SHA256 hash of the `SubjectPublicKeyInfo`
+ *                          of the upstream, which will be used to authenticate
+ *                          it.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when `context` or `upstream_list` was `NULL`
+ * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL when there were problems parsing
+ *         the `upstream_list`.
+ */
 getdns_return_t
 getdns_context_set_upstream_recursive_servers(getdns_context *context,
     getdns_list *upstream_list);
 
+/**
+ * Set the maximum UDP payload size advertised in a EDNS0 OPT record.
+ * When not set (the default), outgoing values will adhere to the suggestions
+ * in RFC 6891 and may follow a scheme that uses multiple values to maximize
+ * receptivity.
+ * @see getdns_context_get_edns_maximum_udp_payload_size
+ * @see getdns_context_unset_edns_maximum_udp_payload_size
+ * @param context The context to configure
+ * @param value The maximum UDP payload size advertised in a EDNS0 OPT record.
+ *              The value must be between 512 and 65536
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_edns_maximum_udp_payload_size(getdns_context *context,
     uint16_t value);
 
+/**
+ * Set the rcode advertised in a EDNS0 OPT record.  The default is 0.
+ * @see getdns_context_get_edns_extended_rcode
+ * @param context The context to configure
+ * @param value  A value between 0 and 255.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_edns_extended_rcode(getdns_context *context,
     uint8_t value);
 
+/**
+ * Set the version advertised in a EDNS0 OPT record.  The default is 0.
+ * @see getdns_context_get_edns_version
+ * @param context The context to configure
+ * @param value  A value between 0 and 255.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_edns_version(getdns_context *context, uint8_t value);
 
+/**
+ * Set the DO ibit advertised in a EDNS0 OPT record.  The default is 0.
+ * However use of any of the dnssec_* extension will override this setting
+ * and set the DO bit.
+ * @see getdns_context_get_edns_do_bit
+ * @param context The context to configure
+ * @param value  A value between 0 and 1.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_edns_do_bit(getdns_context *context, uint8_t value);
 
+/**
+ * Specify custom memory management functions to be used with this context.
+ * The given memory management functions will be used for creating the response
+ * dicts. The response dicts inherit the custom memory management functions
+ * from the context and will deallocate themselves (and their members) with the
+ * custom deallocator. By default, the system `malloc`, `realloc`, and `free` are used.
+ * @param context The context to configure
+ * @param malloc A custom memory allocator.  The default is `malloc`.
+ * @param realloc A custom memory reallocator. The default is `realloc`.
+ * @param free A custom memory deallocator. The default is `free`.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_memory_functions(getdns_context *context,
     void *(*malloc) (size_t),
@@ -1233,6 +1742,22 @@ getdns_context_set_memory_functions(getdns_context *context,
     void (*free) (void *)
     );
 
+/**
+ * Specify custom extended memory management functions to be used with this
+ * context.  The value of `userarg` argument will be passed to the custom
+ * `malloc`, `realloc`, and `free`.
+ * The response dicts inherit the custom memory management functions
+ * from the context and will deallocate themselves (and their members) with the
+ * custom deallocator. By default, the system `malloc`, `realloc`, and `free` are used.
+ * @param context The context to configure
+ * @param userarg This value will be passed as the `userarg` argument to the
+ *                custom `malloc`, `realloc` and `free` function.
+ * @param malloc A custom memory allocator.  The default is a wrapper for `malloc`.
+ * @param realloc A custom memory reallocator. The default is a wrapper for `realloc`.
+ * @param free A custom memory deallocator. The default is a wrapper for `free`.
+ * @return GETDNS_RETURN_GOOD when successful. 
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL
+ */
 getdns_return_t
 getdns_context_set_extended_memory_functions(getdns_context *context,
     void *userarg,
@@ -1243,7 +1768,22 @@ getdns_context_set_extended_memory_functions(getdns_context *context,
 /** @}
  */
 
-/* api information support */
+/**
+ * Retrieve information about the API itself and inspect the current context.
+ * The returned dictionary can be used with getdns_context_config() directly
+ * to configure another context with precisely these settings.
+ * @param context The context from which to get the information
+ * @return A getdns_dict containing the following name/value pairs:
+ *         - `version_string` (a bindata) represents the version string for this version of the DNS API.
+ *         - `implementation_string` (a bindata) is a string showing which
+ *           implementation of the getdns API this is.  In our implementation
+ *           this will always be set to "https://getdnsapi.net"
+ *         - resolution_type (an int) is the type of resolver that the API is
+ *            acting as in this context: GETDNS_RESOLUTION_RECURSING or
+ *            GETDNS_RESOLUTION_STUB.
+ *         - all_context (a dict) with names for all the other settings in
+ *           context.
+ */
 getdns_dict*
 getdns_context_get_api_information(getdns_context* context);
 

src/getdns/getdns_ext_libev.h

@@ -48,7 +48,21 @@ struct ev_loop;
 /**
  *  \ingroup eventloops
  */
-/* For libevent, which we are using for these examples */
+/**
+ * Associate the libev ev_loop with the context, so that all
+ * asynchronous requests will schedule Input/Output with it.
+ * Synchronous requests will still use a default eventloop based on `poll()`.
+ * Applications need to @code #include <getdns/getdns_ext_libev.h> @endcode
+ * and link with libgetdns_ext_ev to use this function.
+ * getdns needs to have been configured with --with-libev for this 
+ * extension to be available.
+ * @param context The context to configure
+ * @param ev_loop The libev event loop to associate with this context.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_BAD_CONTEXT when context is NULL
+ * @return GETDNS_RETURN_INVALID_PARAMETER when ev_loop is NULL
+ * @return GETDNS_RETURN_MEMORY_ERROR when memory could not be allocated
+ */
 getdns_return_t
 getdns_extension_set_libev_loop(struct getdns_context *context,
     struct ev_loop *ev_loop);

src/getdns/getdns_ext_libevent.h

@@ -47,7 +47,21 @@ struct event_base;
 /**
  *  \ingroup eventloops
  */
-/* For libevent, which we are using for these examples */
+/**
+ * Associate the libevent event_base with the context, so that all
+ * asynchronous requests will schedule Input/Output with it.
+ * Synchronous requests will still use a default eventloop based on `poll()`.
+ * Applications need to @code #include <getdns/getdns_ext_libevent.h> @endcode
+ * and link with libgetdns_ext_event to use this function.
+ * getdns needs to have been configured with --with-libevent for this 
+ * extension to be available.
+ * @param context The context to configure
+ * @param this_event_base The libevent event base to associate with this context.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_BAD_CONTEXT when context is NULL
+ * @return GETDNS_RETURN_INVALID_PARAMETER when this_event_base is NULL
+ * @return GETDNS_RETURN_MEMORY_ERROR when memory could not be allocated
+ */
 getdns_return_t
 getdns_extension_set_libevent_base(struct getdns_context *context,
     struct event_base *this_event_base);

src/getdns/getdns_ext_libuv.h

@@ -47,7 +47,21 @@ struct uv_loop_s;
 /**
  *  \ingroup eventloops
  */
-/* For libevent, which we are using for these examples */
+/**
+ * Associate the libuv uv_loop with the context, so that all
+ * asynchronous requests will schedule Input/Output with it.
+ * Synchronous requests will still use a default eventloop based on `poll()`.
+ * Applications need to @code #include <getdns/getdns_ext_libuv.h> @endcode 
+ * and link with libgetdns_ext_uv to use this function.
+ * getdns needs to have been configured with --with-libuv for this 
+ * extension to be available.
+ * @param context The context to configure
+ * @param uv_loop The libuv event loop to associate with this context.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_BAD_CONTEXT when context is NULL
+ * @return GETDNS_RETURN_INVALID_PARAMETER when uv_loop is NULL
+ * @return GETDNS_RETURN_MEMORY_ERROR when memory could not be allocated
+ */
 getdns_return_t
 getdns_extension_set_libuv_loop(struct getdns_context *context,
     struct uv_loop_s *uv_loop);

src/getdns/getdns_extra.h.in

@@ -157,69 +157,207 @@ typedef enum getdns_tls_authentication_t {
  *  @{
  */
 
+/**
+ * The type of callback function that is used by the callbacks in an
+ * getdns_eventloop_event.
+ * @param userarg This will have the value of the userarg attribute of the
+ *                getdns_eventloop_event struct in which this callback was
+ *                present.
+ */
 typedef void (*getdns_eventloop_callback)(void *userarg);
 
-/* context extension event data */
-typedef struct getdns_eventloop_event {
+
+typedef struct getdns_eventloop_event getdns_eventloop_event;
+/**
+ * getdns uses an event loop abstraction layer to interface with event loop
+ * extensions. The extension accepts registration of getdns_eventloop_events
+ * and translates them to the underlying event loop API for which it is an
+ * extension.  Also applications using getdns can use the abstraction layer
+ * themselves and in doing so inherit the flexibility being immediately 
+ * compatible with all the event loop systems for which there is an extension
+ * already (i.e. libevent, libev and libuv).
+ */
+struct getdns_eventloop_event {
+	/**
+	 * The userarg argument that will be passed to the
+	 * getdns_eventloop_callbacks when they are fired.
+	 */
 	void *userarg;
+
+	/**
+	 * When not NULL, it will be fired when the associated file descriptor
+	 * is readable.
+	 */
 	getdns_eventloop_callback read_cb;
+
+	/**
+	 * When not NULL, it will be fired when the associated file descriptor
+	 * is writable.
+	 */
 	getdns_eventloop_callback write_cb;
+
+	/**
+	 * When not NULL, it will be fired when the during scheduling specified
+	 * timeout time has passed.
+	 */
 	getdns_eventloop_callback timeout_cb;
 
-	/* Pointer to the underlying event
-	 * that the eventloop extension will create and free.
+	/**
+	 * Pointer to the underlying event
+	 * that an eventloop extension must manage (i.e. create and free.)
 	 */
 	void *ev;
-} getdns_eventloop_event;
+};
 
 typedef struct getdns_eventloop_vmt getdns_eventloop_vmt;
+
+/**
+ * The manifestation of the event loop abstraction layer.  Event loop
+ * extension implementers should extend this with attributed needed for the
+ * underlying event loop.
+ * The current event loop extension can be obtained with the
+ * getdns_context_get_eventloop() function.
+ */
 typedef struct getdns_eventloop {
+	/**
+	 * The Virtual Method Table providing the interface for this specific
+	 * event loop extension.
+	 */
 	getdns_eventloop_vmt *vmt;
 } getdns_eventloop;
 
-/* A prototype for a method having no arguments and not return value. */
+/**
+ * The function prototype for the `cleanup` and `run` functions in an getdns
+ * event loop's Virtual Method Table.  These methods have no (extra) arguments
+ * and return nothing.
+ * @param loop The event loop to `run` or `cleanup`
+ */
 typedef void (*getdns_eventloop_noargs)(getdns_eventloop *loop);
 
-/* Call the extension to schedule an event
- *
+/**
+ * The function prototype for the `schedule` function in an event loop
+ * Virtual Method Table.
  * The getdns_eventloop_event must be provided by the caller with the callbacks
  * and userarg therein already supplied (by the caller). This function will set
  * the ev pointer (in the getdns_eventloop_event) to refer to the underlying
  * (extension) event.
+ * @param loop The event loop for which to register the event.
+ * @param fd The file descriptor for which to schedule the read_cb and/or
+ *           write_cb callbacks.
+ * @param timeout The number of milliseconds that must pass without read
+ *        and/or write event after which the timeout_cb callback is fired.
+ * @param ev The event with all attributes provisioned, except for the ev->ev
+ *           attribute, which will be provisioned by the implementation of
+ *           the schedule method.
+ * @return GETDNS_RETURN_GOOD when successful and an error code otherwise.
  */
 typedef getdns_return_t (*getdns_eventloop_schedule)(getdns_eventloop *loop,
     int fd, uint64_t timeout, getdns_eventloop_event *ev);
 
-/* Call the extension to clean a scheduled event */
+/**
+ * The function prototype for the `clean` function in an event loop
+ * Virtual Method Table.
+ * The implementation must clear the event (which is referred to with
+ * ev->ev) in the underlying event loop and make ev->ev NULL when done.
+ * getdns will test for this value to determine if events are scheduled or not.
+ * @param loop The event loop for which to event needs to be cleared.
+ * @param ev [in,out] The event with the ev->ev attribute referring to the
+ *           underlying event. ev->ev must be set to NULL after the event
+ *           was cleared.
+ * @return GETDNS_RETURN_GOOD when successful and an error code otherwise.
+ */
 typedef getdns_return_t (*getdns_eventloop_clear)
     (getdns_eventloop *loop, getdns_eventloop_event *ev);
 
+/**
+ * The function prototype for the `run_once` function in an event loop
+ * Virtual Method Table.  The implementation must do a single round of
+ * firing callbacks, either blocking or not.
+ * @param loop The event loop to run
+ * @param blocking When 0, only callbacks for file descriptors that are
+ *                 immediately readable or writable or timeouts that have
+ *                 passed will be fired. When 1, the eventloop will wait
+ *                 until the first callback can be fired, either because a
+ *                 associated file descriptor has become readable or writeable,
+ *                 or because a timeout time passed.
+ */
 typedef void (*getdns_eventloop_run_once)(getdns_eventloop *loop,int blocking);
 
- /* Virtual Method Table */
+/**
+ * The Virtual Method Table providing the interface for this specific
+ * event loop extension.
+ */
 struct getdns_eventloop_vmt {
+	/**
+	 * Destroy the getdns_eventloop and the associated underlying event
+	 * loop for which it is an extension.
+	 */
 	getdns_eventloop_noargs     cleanup;
+
+	/**
+	 * Schedule a getdns_eventloop_event with a getdns_eventloop.
+	 */
 	getdns_eventloop_schedule   schedule;
+
+	/**
+	 * Clear a getdns_eventloop_event
+	 */
 	getdns_eventloop_clear      clear;
+
+	/**
+	 * Run the getdns_eventloop until it has no getdns_eventloop_events
+	 * scheduled.
+	 */
 	getdns_eventloop_noargs     run;
+
+	/**
+	 * Do a single iteration of firing callbacks for scheduled events
+	 * and then return.
+	 */
 	getdns_eventloop_run_once   run_once;
 };
 
-/* set an event loop extension on the context */
+/**
+ * Configure a context to use the specified event loop abstraction extension.
+ * This function must be called with an provisioned eventloop by the
+ * event loop extension registration functions.
+ * @see getdns_context_get_eventloop
+ * @param context The context to configure
+ * @param eventloop The event loop abstraction extension with a completely
+ *                  provisioned Virtual Method Table and other associated
+ *                  data which is opaque to the user.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or eventloop were NULL.
+ */
 getdns_return_t
 getdns_context_set_eventloop(getdns_context* context,
     getdns_eventloop *eventloop);
 
-/* get the currently active (pluggable) eventloop from the context */
+/**
+ * Get the current event loop abstraction extension from the context
+ * Applications using getdns can use the event loop abstraction extension
+ * themselves directly to inherit the flexibility being immediately 
+ * compatible with all the event loop systems for which there is an extension
+ * (i.e. libevent, libev and libuv).
+ * @see getdns_context_set_eventloop
+ * @param context [in] The context to get the eventloop from
+ * @param eventloop [out] The currently active  event loop abstraction extension
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or evenloop were NULL
+ */
 getdns_return_t
 getdns_context_get_eventloop(getdns_context* context,
     getdns_eventloop **eventloop);
 
-/* detach the eventloop from the context */
-getdns_return_t
-getdns_context_detach_eventloop(getdns_context *context);
-
-/* Run the context's event loop until nothing more to do */
+/**
+ * Run the context's event loop until nothing more to do.
+ * This is equivalend to:
+ * ```c
+ * if (getdns_context_get_eventloop(context, &loop) == GETDNS_RETURN_GOOD)
+ * 	loop->vmt->run(loop);
+ * ```
+ * @param context The context which event loop to run.
+ */
 void
 getdns_context_run(getdns_context *context);
 /** @}
@@ -230,8 +368,10 @@ getdns_context_run(getdns_context *context);
  * \defgroup Ucontextset Additional getdns_context_set functions
  *  @{
  */
+
 /**
  * Register a callback function for context changes.
+ * @see getdns_context_set_context_update_callback
  * @param context The context to monitor for changes
  * @param userarg A user defined argument that will be passed to the callback
  *                function.
@@ -246,36 +386,120 @@ getdns_return_t
 getdns_context_set_update_callback(getdns_context *context, void *userarg,
     void (*value) (getdns_context *, getdns_context_code_t, void *));
 
-/* Enable the return_dnssec_status extension on every request.
-   value is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE
-   returns GETDNS_RETURN_GOOD on success or GETDNS_RETURN_INVALID_PARAMETER
-   if context or value is invalid */
+/**
+ * Enable the return_dnssec_status extension on every request.
+ * @param context The context to configure
+ * @param enabled is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER if context or value is invalid
+ */
 getdns_return_t getdns_context_set_return_dnssec_status(
     getdns_context *context, int enabled);
 
-/* tells underlying unbound to use background threads or fork */
-getdns_return_t getdns_context_set_use_threads(getdns_context* context,
-    int use_threads);
-
+/**
+ * Configure context for oppertunistic or scrict usage profile with DNS
+ * over TLS.
+ * @see getdns_context_get_tls_authentication
+ * @param context The context to configure
+ * @param value is either GETDNS_AUTHENTICATION_REQUIRED for the strict
+ *              usage profile or GETDNS_AUTHENTICATION_NONE for opportunistic
+ *              profile.
+ *              See #getdns_context_set_upstream_recursive_servers
+ *              for details on how to configure credentials per upstream.
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an
+ *         invalid value.
+ */
 getdns_return_t
 getdns_context_set_tls_authentication(
     getdns_context *context, getdns_tls_authentication_t value);
 
+/**
+ * Configure context to round robin queries over the available upstreams
+ * when resolving with the stub resolution type.
+ * @see getdns_context_get_round_robin_upstreams
+ * @param context The context to configure
+ * @param value is either 1 to enable and 0 to disable round robin.
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an
+ *         invalid value.
+ */
 getdns_return_t
 getdns_context_set_round_robin_upstreams(getdns_context *context, uint8_t value);
 
+/**
+ * Configure the amount of seconds a TLS connection should not be tried with
+ * an upstream when it has never been tried before.  Default is 3600 which is
+ * one hour.
+ * @see getdns_context_get_tls_backoff_time
+ * @param context The context to configure
+ * @param value Number of seconds before an attempt to setup DNS over TLS,
+ *              with an upstream for which setting up an TLS connection has
+ *              never been successful before, will be retried.
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER if context is null.
+ */
 getdns_return_t
 getdns_context_set_tls_backoff_time(getdns_context *context, uint16_t value);
 
+/**
+ * Configure the number of times getdns retries to setup DNS over TLS with a
+ * specific upstream, before it decides to give up for tls_backoff_time
+ * seconds.  The default is 2.
+ * @see getdns_context_get_tls_connection_retries
+ * @param context The context to configure
+ * @param value Number of attempts to retry setting up a DNS over TLS
+ *              connection before giving up.
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER if context is null.
+ */
 getdns_return_t
 getdns_context_set_tls_connection_retries(getdns_context *context, uint16_t value);
 
+/**
+ * Configure context to sent queries with the EDNS Client Subnet option set
+ * to hide the originating network when resolving in stub resolution.
+ * The default is 0 (disabled).
+ * @see getdns_context_get_edns_client_subnet_private
+ * @param context The context to configure
+ * @param value is either 1 to enable and 0 to disable.
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an
+ *         invalid value.
+ */
 getdns_return_t
 getdns_context_set_edns_client_subnet_private(getdns_context *context, uint8_t value);
 
+/**
+ * Configure context to pad each outgoing query over TLS to a multiple of the
+ * requested blocksizes.  A value of 0 means disable, and a value of 1 means
+ * to "pad using a sensible policy".  The default is 1 (pad using sensible policy).
+ * @see getdns_context_get_tls_query_padding_blocksize
+ * @param context The context to configure
+ * @param value The requested block size to pad to, or 0 to disable, or 1 to
+ *              indicate that the library should use a sinsible policy.
+ *              Currently that just means to pad to a multiple of 128 octets for
+ *              outgoing queries, but this might change in the future.
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an
+ *         invalid value.
+ */
 getdns_return_t
 getdns_context_set_tls_query_padding_blocksize(getdns_context *context, uint16_t value);
 
+/**
+ * Configure context to advertise maximum UDP payload size values, that
+ * adhere to the suggestions in RFC 6891 and may follow a scheme that uses
+ * multiple values to maximize receptivity. In practice with our implementation
+ * this means 1432 for IPv4 upstreams and 1232 for IPv6 upstreams.
+ * The default is to have the edns maximum UDP payload size to be unset and
+ * thus use the adaptive scheme.
+ * @see getdns_context_set_edns_maximum_udp_payload_size
+ * @see getdns_context_get_edns_maximum_udp_payload_size
+ * @param context The context to configure
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER if context is null.
+ */
 getdns_return_t
 getdns_context_unset_edns_maximum_udp_payload_size(getdns_context *context);
 /** @}
@@ -285,93 +509,345 @@ getdns_context_unset_edns_maximum_udp_payload_size(getdns_context *context);
   * \defgroup Ucontextget Additional getdns_context_get functions
   *  @{
   */
-/** begin getters **/
+
+/**
+ * Get the current resolution type setting from this context.
+ * @see getdns_context_set_resolution_type
+ * @param context [in] The context from which to get the setting
+ * @param value [out] The resolution type, either GETDNS_RESOLUTION_RECURSING
+ *              or GETDNS_RESOLUTION_STUB.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_resolution_type(getdns_context *context,
     getdns_resolution_t* value);
 
-/** users must call free on the resulting namespaces if not NULL */
+/**
+ * Get a copy of the namespaces list setting from this context.
+ * Users must call free on the resulting namespaces if not NULL
+ * @see getdns_context_set_namespaces
+ * @param context [in] The context from which to get the setting
+ * @param namespace_count [out] The length of the list.
+ * @param namespaces [out] The returned namespaces list.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.
+ */
 getdns_return_t
 getdns_context_get_namespaces(getdns_context *context,
     size_t* namespace_count, getdns_namespace_t **namespaces);
 
+/**
+ * Get what transports are used for DNS lookups.
+ * @see getdns_context_set_dns_transport
+ * @see getdns_context_get_dns_transport_list
+ * @see getdns_context_set_dns_transport_list
+ * @param context [in] The context from which to get the setting
+ * @param value [out] The transport to use for DNS lookups.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.
+ */
 getdns_return_t
 getdns_context_get_dns_transport(getdns_context *context,
     getdns_transport_t* value);
 
+/**
+ * Get a copy of the transports list setting from this context.
+ * Users must call free on the resulting transports if not NULL
+ * @see getdns_context_set_dns_transport_list
+ * @see getdns_context_get_dns_transport
+ * @see getdns_context_set_dns_transport
+ * @param context [in] The context from which to get the setting
+ * @param transport_count [out] The length of the list.
+ * @param transports [out] The returned transports list.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.
+ */
 getdns_return_t
 getdns_context_get_dns_transport_list(getdns_context *context,
     size_t* transport_count, getdns_transport_list_t **transports);
 
+/**
+ * Get the current limit for oustanding queries setting from this context.
+ * @see getdns_context_set_limit_outstanding_queries
+ * @param context [in] The context from which to get the setting
+ * @param limit [out] The current limit for oustanding queries
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or limit was NULL.
+ */
 getdns_return_t
 getdns_context_get_limit_outstanding_queries(getdns_context *context,
     uint16_t* limit);
 
+/**
+ * Get the current number of milliseconds the API will wait for request
+ * to return setting from this context.
+ * @see getdns_context_set_timeout
+ * @param context [in] The context from which to get the setting
+ * @param timeout [out] The number of milliseconds the API will wait for a
+ *                      response.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or limit was NULL.
+ */
 getdns_return_t
 getdns_context_get_timeout(getdns_context *context, uint64_t* timeout);
 
+/**
+ * Get the current number of milliseconds the API will leave an idle TCP or TLS
+ * connection open for (idle means no outstanding responses and no pending
+ * queries).
+ * @see getdns_context_set_idle_timeout
+ * @param context [in] The context from which to get the setting
+ * @param timeout [out] The number of milliseconds the API will leave an idle TCP
+  *                     or TLS connection open for
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or timeout was NULL.
+ */
 getdns_return_t
 getdns_context_get_idle_timeout(getdns_context *context, uint64_t* timeout);
 
+/**
+ * Get the setting that says whether or not DNS queries follow redirects.
+ * @see getdns_context_set_follow_redirects
+ * @param context [in] The context from which to get the setting
+ * @param value [out] Either GETDNS_REDIRECTS_FOLLOW or GETDNS_REDIRECTS_DO_NOT_FOLLOW
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_follow_redirects(getdns_context *context,
     getdns_redirects_t* value);
 
+/**
+ * Get a copy of the list of addresses in use for looking up top-level domains
+ * in use by the context.
+ * Callers are responsible for deallocating the returned list with
+ * #getdns_list_destroy()
+ * @see getdns_context_set_dns_root_servers
+ * @param context [in] The context from which to get the setting
+ * @param addresses [out] A copy of the list of dns root servers in use for
+ *                        looking up top level domains.  The caller must 
+ *                        destroy this list.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or adresses was NULL.
+ * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
+ */
 getdns_return_t
 getdns_context_get_dns_root_servers(getdns_context *context,
     getdns_list **addresses);
 
+/**
+ * Get whether, how and when a suffix is appended to a query string with
+ * the context.
+ * @see getdns_context_set_append_name
+ * @param context [in] The context from which to get the setting
+ * @param value [out] GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST,
+ *              GETDNS_APPEND_NAME_ALWAYS,
+ *              GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,
+ *              GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE,
+ *              or GETDNS_APPEND_NAME_NEVER
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_append_name(getdns_context *context,
     getdns_append_name_t* value);
 
+/**
+ * Get a copy of the list of suffixes to be appended based on the value off the 
+ * append_name setting in use by context
+ * Callers are responsible for deallocating the returned list with
+ * #getdns_list_destroy()
+ * @see getdns_context_set_suffix
+ * @param context [in] The context from which to get the setting
+ * @param value [out] A copy of the list of suffixes. The caller must destroy
+ *                    this list.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
+ */
 getdns_return_t
 getdns_context_get_suffix(getdns_context *context, getdns_list **value);
 
+/**
+ * Get a copy of the list of DNSSEC trust anchors in use by context.
+ * Callers are responsible for deallocating the returned list with
+ * #getdns_list_destroy()
+ * @see getdns_context_set_dnssec_trust_anchors
+ * @param context [in] The context from which to get the setting
+ * @param value [out] A copy of the list of DNSSEC trust anchors.
+ *                    The caller must destroy this list.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
+ */
 getdns_return_t
 getdns_context_get_dnssec_trust_anchors(getdns_context *context,
     getdns_list **value);
 
+/**
+ * Get the allowed DNSSEC skew setting from context
+ * @see getdns_context_set_dnssec_allowed_skew
+ * @param context [in] The context from which to get the setting
+ * @param value [out] The number of seconds of skew that is allowed in either
+ *              direction when checking an RRSIG's Expiration and Inception
+ *              fields.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_dnssec_allowed_skew(getdns_context *context,
     uint32_t* value);
 
+/**
+ * Get a copy of the list of upstream that will be targeted in stub resolution
+ * mode.
+ * Callers are responsible for deallocating the returned list with
+ * #getdns_list_destroy()
+ * @see getdns_context_set_upstream_recursive_servers
+ * @param context [in] The context from which to get the setting
+ * @param upstream_list [out] A copy of the list of upstreams.
+ *                    The caller must destroy this list.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
+ */
 getdns_return_t
 getdns_context_get_upstream_recursive_servers(getdns_context *context,
     getdns_list **upstream_list);
 
+/**
+ * Get the maximum UDP payload size advertised in an EDNS0 OPT record
+ * setting from context
+ * @see getdns_context_set_edns_maximum_udp_payload_size
+ * @see getdns_context_unset_edns_maximum_udp_payload_size
+ * @param context [in] The context from which to get the setting
+ * @param value [out] the maximum UDP payload size advertised in an EDNS0
+ *                    OPT record.  When the value is unset, 0 is returned.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_edns_maximum_udp_payload_size(getdns_context *context,
     uint16_t* value);
 
+/**
+ * Get the rcode advertised in an EDNS0 OPT record setting from context
+ * @see getdns_context_set_edns_extended_rcode
+ * @param context [in] The context from which to get the setting
+ * @param value [out] The rcode advertised in an EDNS0 OPT record
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_edns_extended_rcode(getdns_context *context,
     uint8_t* value);
 
+/**
+ * Get the version advertised in an EDNS0 OPT record setting from context
+ * @see getdns_context_set_edns_version
+ * @param context [in] The context from which to get the setting
+ * @param value [out] The version advertised in an EDNS0 OPT record
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_edns_version(getdns_context *context, uint8_t* value);
 
+/**
+ * Get the DO bit advertised in an EDNS0 OPT record setting from context
+ * @see getdns_context_set_edns_do_bit
+ * @param context [in] The context from which to get the setting
+ * @param value [out] 1 if the DO bit is advertised in EDNS0 OPT records,
+ *                    0 otherwise.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_edns_do_bit(getdns_context *context, uint8_t* value);
 
+/**
+ * Get whether queries with this context will have the EDNS Client Subnet 
+ * option set to hide the originating network when resolving in stub 
+ * resolution.
+ * @see getdns_context_set_edns_do_bit
+ * @param context [in] The context from which to get the setting
+ * @param value [out] 1 if the setting is on, 0 otherwise
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_edns_client_subnet_private(getdns_context *context, uint8_t* value);
 
+/**
+ * Get the blocksize that will be used to pad outgoing queries over TLS.
+ * @see getdns_context_set_tls_query_padding_blocksize
+ * @param context [in] The context from which to get the setting
+ * @param value [out] The padding blocksize, or 0 if padding is disabled,
+ *                    or 1 if the setting is to pad using a sensible policy.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_tls_query_padding_blocksize(getdns_context *context, uint16_t* value);
 
+/**
+ * Get whether the upstream needs to be authenticated whith DNS over TLS.
+ * @see getdns_context_set_tls_authentication
+ * @param context [in] The context from which to get the setting
+ * @param value [out] is either GETDNS_AUTHENTICATION_REQUIRED if
+ *                    authentication is required, or GETDNS_AUTHENTICATION_NONE
+ *                    if authentication is optional.  When credentials are
+ *                    available, the API will still try to authenticate the
+ *                    upstream.
+ *                    See #getdns_context_set_upstream_recursive_servers
+ *                    for details on how to configure credentials per upstream.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_tls_authentication(getdns_context *context,
     getdns_tls_authentication_t* value);
 
+/**
+ * Get whether the context is configured to round robin queries over the available
+ * upstreams.
+ * @see getdns_context_get_round_robin_upstreams
+ * @param context [in] The context from which to get the setting
+ * @param value [out] 1 if the setting is on, 0 otherwise
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_round_robin_upstreams(getdns_context *context,
     uint8_t* value);
 
+/**
+ * Get the amount of seconds a TLS connection should not be tried with
+ * an upstream when it has never been tried before.
+ * @see getdns_context_set_tls_backoff_time
+ * @param context [in] The context from which to get the setting
+ * @param value [out] Number of seconds before an attempt to setup DNS over TLS,
+ *              with an upstream for which setting up an TLS connection has
+ *              never been successful before, will be retried.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_tls_backoff_time(getdns_context *context,
     uint16_t* value);
 
+/**
+ * Get the number of times getdns retries to setup DNS over TLS with a
+ * specific upstream, before it decides to give up for tls_backoff_time
+ * seconds.
+ * @see getdns_context_set_tls_connection_retries
+ * @param context [in] The context from which to get the setting
+ * @param value [out] Number of attempts to retry setting up a DNS over TLS
+ *              connection before giving up.
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
+ */
 getdns_return_t
 getdns_context_get_tls_connection_retries(getdns_context *context,
     uint16_t* value);
@@ -402,9 +878,36 @@ getdns_context_get_update_callback(getdns_context *context, void **userarg,
  *  @{
  */
 
+/**
+ * Get the version number of this implementation.
+ * @return The version number as string.  For example "@GETDNS_VERSION@".
+ */
 const char *getdns_get_version(void);
+
+/**
+ * Get the version number of this implementation as number.
+ * @return The version number as number.  For example @GETDNS_NUMERIC_VERSION@.
+ *         - The most significant byte of this uint32_t is the Major version.
+ *         - The second most significant byte is the Minor version.
+ *         - The third most significant byte the Patch version.
+ */
 uint32_t getdns_get_version_number(void);
+
+/**
+ * Get the version of the getdns API specification this library implements
+ * as a string.
+ * @return The API specification version as string. For example "@API_VERSION@"
+ */
 const char *getdns_get_api_version(void);
+
+/**
+ * Get the version of the getdns API specification this library implements
+ * as a number.
+ * @return The API specification version as number. For example "@API_NUMERIC_VERSION@"
+ *         - The most significant 16 bits represent the year.
+ *         - The third most significant byte the day.
+ */
+
 uint32_t getdns_get_api_version_number(void);
 
 /**
@@ -416,16 +919,35 @@ uint32_t getdns_get_api_version_number(void);
  */
 const char *getdns_get_errorstr_by_id(uint16_t err);
 
-/* dict util */
-/* set a string as bindata */
-getdns_return_t getdns_dict_util_set_string(getdns_dict * dict,
-    char *name, const char *value);
-
-/* get a string from a dict.  the result must be freed if valid */
-getdns_return_t getdns_dict_util_get_string(getdns_dict * dict,
-    char *name, char **result);
-
+/**
+ * Create a new entry in the dictionary, or replace the value of an existing
+ * entry, with a getdns_bindata representing a string.  The string will be
+ * copied.  The size of the bindata will be strlen(value), though there will
+ * be a '\0' byte directly after the size'd position even, though the size
+ * argument suggests that this would not be part of the bindata's date space.
+ * @see getdns_dict_set_bindata
+ * @param dict dictionary in which to add or change the value
+ * @param name key that identifies which item in the dictionary to add/change
+ * @param value string to be copied and stored in the bindata at key
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER when one of the arguments was NULL
+ * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
+ */
+getdns_return_t
+getdns_dict_util_set_string(getdns_dict *dict, char *name, const char *value);
 
+/**
+ * Get the string associated with the speicifed name.  The string should not
+ * be free()'d by the caller.
+ * @see getdns_dict_get_bindata
+ * @param dict dictionary from which to fetch the bindata
+ * @param name a name/key value to look up in the dictionary
+ * @param result The bindata's data value
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist
+ */
+getdns_return_t
+getdns_dict_util_get_string(getdns_dict * dict, char *name, char **result);
 
 /**
  * Validate replies or resource records.
@@ -1152,19 +1674,56 @@ getdns_reply(getdns_context *context,
  * \defgroup Uutilityfunctionsdeprecated  Additional utility functions (will be deprecated)
  *  @{
  */
-/* WARNING! Function getdns_strerror is not in the API specification and
+/**
+ * WARNING! Function getdns_strerror is not in the API specification and
  * is likely to be removed from future versions of our implementation, to be
  * replaced by getdns_get_errorstr_by_id or something similar.
  * Please use getdns_get_errorstr_by_id instead of getdns_strerror.
  */
 getdns_return_t getdns_strerror(getdns_return_t err, char *buf, size_t buflen);
 
+/**
+ * Runs the event loop once non blocking.
+ * WARNING! Do not use this function.  This function will be removed in
+ * future versions of getdns.
+ */
 getdns_return_t getdns_context_process_async(getdns_context* context);
 
-/* Async support */
+/**
+ * Return the number of pending requests and the point of time of the next
+ * timeout.
+ * WARNING! Do not use this function.  This function will be removed in
+ * future versions of getdns.
+ */
 uint32_t getdns_context_get_num_pending_requests(getdns_context* context,
     struct timeval* next_timeout);
 
+/**
+ * Detach the eventloop from the context.  Resets the context with the default
+ * event loop based on poll().  WARNING!  Do not use this function.  It is For
+ * internal use only and may disappear in future releases.
+ * @param context The context to reset to default event loop usage
+ * @return GETDNS_RETURN_GOOD when successful
+ * @return GETDNS_RETURN_INVALID_PARAMETER when context is NULL
+ */
+getdns_return_t
+getdns_context_detach_eventloop(getdns_context *context);
+
+/**
+ * Tell underlying unbound context to use background threads or fork.
+ * This is only relevant for libunbound version before 1.5.9.  After this
+ * version the underlying unbound will share the event loop with getdns
+ * eliminating the use for threads.  Since the need for this function is
+ * doubtful and likely to disappear in the future, use is strongly
+ * discouraged.
+ * @param context The context to configure
+ * @param use_threads is either 1 to use threads, or 0 to use fork
+ * @return GETDNS_RETURN_GOOD on success
+ * @return GETDNS_RETURN_INVALID_PARAMETER if context is NULL
+ */
+getdns_return_t getdns_context_set_use_threads(getdns_context* context,
+    int use_threads);
+
 /** @}
  */
 /** @}

src/mk-symfiles.sh

@@ -3,7 +3,7 @@
 write_symbols() {
 	OUTPUT=$1
 	shift
-	grep 'getdns_[0-9a-zA-Z_]*(' $* | grep -v '^#' | grep -v 'INLINE' \
+	grep 'getdns_[0-9a-zA-Z_]*(' $* | grep -v '^#' | grep -v 'INLINE' | grep -v 'getdns_extra\.h\.in: \* if' \
 	| sed -e 's/(.*$//g' -e 's/^.*getdns_/getdns_/g' | LC_ALL=C sort | uniq > $OUTPUT
 }
 

src/stub.c

@@ -750,7 +750,7 @@ stub_tcp_read(int fd, getdns_tcp_state *tcp, struct mem_funcs *mf)
 
 /* stub_tcp_write(fd, tcp, netreq)
  * will return STUB_TCP_AGAIN when we need to come back again,
- * STUB_TCP_ERROR on error and a query_id on successfull sent.
+ * STUB_TCP_ERROR on error and a query_id on successful sent.
  */
 static int
 stub_tcp_write(int fd, getdns_tcp_state *tcp, getdns_network_req *netreq)

src/test/tests_transports.sh

@@ -10,7 +10,7 @@ TLS_SERVER_KEY="foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9S="
 TLS_SERVER_SS_KEY="pOXrpUt9kgPgbWxBFFcBTbRH2heo2wHwXp1fd4AEVXI="
 TLS_SERVER_WRONG_KEY="foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc1S="
 GOOD_RESULT_SYNC="Status was: At least one response was returned"
-GOOD_RESULT_ASYNC="successfull"
+GOOD_RESULT_ASYNC="successful"
 BAD_RESULT_SYNC="1 'Generic error'"
 BAD_RESULT_ASYNC="callback_type of 703"
 NUM_ARGS=3

src/tools/getdns_query.c

@@ -219,7 +219,7 @@ print_usage(FILE *out, const char *progname)
 	}
 	fprintf(out, "\t-D\tSet edns0 do bit\n");
 	fprintf(out, "\t-d\tclear edns0 do bit\n");
-	fprintf(out, "\t-e <idle_timeout>\tSet idle timeout in miliseconds\n");
+	fprintf(out, "\t-e <idle_timeout>\tSet idle timeout in milliseconds\n");
 	if (!i_am_stubby)
 		fprintf(out, "\t-F <filename>\tread the queries from the specified file\n");
 	fprintf(out, "\t-f <filename>\tRead DNSSEC trust anchors from <filename>\n");
@@ -253,7 +253,7 @@ print_usage(FILE *out, const char *progname)
 	       , i_am_stubby ? "" : "(default = recursing)" );
 	if (!i_am_stubby)
 		fprintf(out, "\t-S\tservice lookup (<type> is ignored)\n");
-	fprintf(out, "\t-t <timeout>\tSet timeout in miliseconds\n");
+	fprintf(out, "\t-t <timeout>\tSet timeout in milliseconds\n");
 	fprintf(out, "\t-v\tPrint getdns release version\n");
 	fprintf(out, "\t-x\tDo not follow redirects\n");
 	fprintf(out, "\t-X\tFollow redirects (default)\n");
@@ -263,7 +263,7 @@ print_usage(FILE *out, const char *progname)
 	fprintf(out, "\t-1\tAppend suffix only to single label after failure\n");
 	fprintf(out, "\t-M\tAppend suffix only to multi label name after failure\n");
 	fprintf(out, "\t-N\tNever append a suffix\n");
-	fprintf(out, "\t-Z <suffixes>\tSet suffixes with the given comma separed list\n");
+	fprintf(out, "\t-Z <suffixes>\tSet suffixes with the given comma separated list\n");
 
 	fprintf(out, "\t-T\tSet transport to TCP only\n");
 	fprintf(out, "\t-O\tSet transport to TCP only keep connections open\n");
@@ -384,7 +384,7 @@ void callback(getdns_context *context, getdns_callback_type_t callback_type,
 	}
 
 	if (callback_type == GETDNS_CALLBACK_COMPLETE) {
-		printf("Response code was: GOOD. Status was: Callback with ID %"PRIu64"  was successfull.\n",
+		printf("Response code was: GOOD. Status was: Callback with ID %"PRIu64"  was successful.\n",
 			trans_id);
 
 	} else if (callback_type == GETDNS_CALLBACK_CANCEL)

src/types-internal.h

@@ -345,7 +345,7 @@ typedef struct getdns_dns_req {
 	/* the transaction id */
 	getdns_transaction_t trans_id;
 
-	/* Absolute time (in miliseconds since epoch),
+	/* Absolute time (in milliseconds since epoch),
 	 * after which this dns request is expired; i.e. timed out
 	 */
 	uint64_t expires;