Doxygen documentation for everything in getdns.h

src/getdns/getdns.h.in

@@ -490,12 +490,30 @@ 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
 {
@@ -503,6 +521,9 @@ typedef enum getdns_data_type
 } getdns_data_type;
 
 
+/**
+ * A  struct to hold binary data.
+ */
 typedef struct getdns_bindata
 {
 	size_t size;
@@ -893,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
@@ -944,7 +974,28 @@ getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);
  */
 /**
  * The type of the callback function that must be registered when scheduling
- * asynchronous requests.
+ * 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,
@@ -1196,27 +1247,90 @@ 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);
 
 /**
@@ -1227,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);
 
@@ -1238,6 +1359,16 @@ 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.
+ * @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,
@@ -1245,73 +1376,339 @@ 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.
+ * @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
+ * @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.  
+ * @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.
+ * @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.
+ * @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.
+ * @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).
+ * @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.
+ * @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
+ * @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.
+ * @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.
+ * @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@.
+ * @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.
+ * @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.
+ * @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.
+ * @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.
+ * @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.
+ * @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 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.
+ * @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),
@@ -1319,6 +1716,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,
@@ -1329,7 +1742,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);