Merge pull request #186 from saradickinson/documentation/doxygen_updates

Initial pass at updating Doxygen modules for getdns.h. Also add info …

doc/getdns_context.3.in

@@ -134,6 +134,16 @@ will be called with a callback_type of GETDNS_CALLBACK_CANCEL.
 getdns_context_destroy() returns after all of the needed cleanup is done and
 callbacks are made.
 
+.LP
+If you are using getdns in a multi-threaded manner, you are then of course using
+the underlying OpenSSL library multi-threaded and the version of that library
+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).  
+Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function.
+
 .HP 3
 .I context
 Used to return the pointer to an opaque structure.  The caller passes the address of a pointer (decl: getdns_context *context; passed as &context) which will be populated as a result of returning from the function.  The result is a newly allocated and initialized context (if there are no errors).  In the getdns_destroy_context function this is the context whose associated memory will be released.

src/getdns/getdns.h.in

@@ -33,6 +33,7 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+
 #ifndef GETDNS_H
 #define GETDNS_H
 
@@ -46,7 +47,10 @@ extern "C" {
 
 #define GETDNS_COMPILATION_COMMENT "@GETDNS_COMPILATION_COMMENT@"
 
-/* Return values */
+/**
+ * \defgroup returntypes Return values
+ * @{
+ */
 typedef enum getdns_return_t {
 	GETDNS_RETURN_GOOD = 0,
 	GETDNS_RETURN_GENERIC_ERROR = 1,
@@ -64,9 +68,11 @@ typedef enum getdns_return_t {
 	GETDNS_RETURN_INVALID_PARAMETER = 311,
 	GETDNS_RETURN_NOT_IMPLEMENTED = 312
 } getdns_return_t;
+/** @}
+ */
 
 /**
- * \defgroup Return values texts
+ * \defgroup returntypestext Return values texts
  * @{
  */
 #define GETDNS_RETURN_GOOD_TEXT "Good"
@@ -89,7 +95,7 @@ typedef enum getdns_return_t {
 
 
 /**
- * \defgroup dnssecvalues DNSSEC values
+ * \defgroup dnssecvalues DNSSEC values and texts
  * @{
  */
 #define GETDNS_DNSSEC_SECURE 400
@@ -106,7 +112,10 @@ typedef enum getdns_return_t {
  */
 
 
-/* Namespace types */
+/**
+ * \defgroup namespacetypes Namespace types
+ * @{
+ */
 typedef enum getdns_namespace_t {
 	GETDNS_NAMESPACE_DNS = 500,
 	GETDNS_NAMESPACE_LOCALNAMES = 501,
@@ -114,9 +123,11 @@ typedef enum getdns_namespace_t {
 	GETDNS_NAMESPACE_MDNS = 503,
 	GETDNS_NAMESPACE_NIS = 504
 } getdns_namespace_t;
+/** @}
+ */
 
 /**
- * \defgroup Namespace types texts
+ * \defgroup namespacetypestext Namespace types texts
  * @{
  */
 #define GETDNS_NAMESPACE_DNS_TEXT "See getdns_context_set_namespaces()"
@@ -128,14 +139,19 @@ typedef enum getdns_namespace_t {
  */
 
 
-/* Resolution types */
+/**
+ * \defgroup resolutiontypes Resolution types
+ * @{
+ */
 typedef enum getdns_resolution_t {
 	GETDNS_RESOLUTION_STUB = 520,
 	GETDNS_RESOLUTION_RECURSING = 521
 } getdns_resolution_t;
+/** @}
+ */
 
 /**
- * \defgroup Resolution types texts
+ * \defgroup resolutiontypestext Resolution types texts
  * @{
  */
 #define GETDNS_RESOLUTION_STUB_TEXT "See getdns_context_set_resolution_type()"
@@ -144,14 +160,19 @@ typedef enum getdns_resolution_t {
  */
 
 
-/* Redirect policies */
+/**
+ * \defgroup redirectpolicytype Redirect policies
+ * @{
+ */
 typedef enum getdns_redirects_t {
 	GETDNS_REDIRECTS_FOLLOW = 530,
 	GETDNS_REDIRECTS_DO_NOT_FOLLOW = 531
 } getdns_redirects_t;
+/** @}
+ */
 
 /**
- * \defgroup Redirect policies texts
+ * \defgroup redirectpoliciestext Redirect policies texts
  * @{
  */
 #define GETDNS_REDIRECTS_FOLLOW_TEXT "See getdns_context_set_follow_redirects()"
@@ -160,16 +181,21 @@ typedef enum getdns_redirects_t {
  */
 
 
-/* Transport arrangements */
+/**
+ * \defgroup transporttypes Transport arrangements 
+ * @{
+ */
 typedef enum getdns_transport_t {
 	GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP = 540,
 	GETDNS_TRANSPORT_UDP_ONLY = 541,
 	GETDNS_TRANSPORT_TCP_ONLY = 542,
 	GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN = 543
 } getdns_transport_t;
+/** @}
+*/
 
 /**
- * \defgroup Transport arrangements texts
+ * \defgroup transporttypestext Transport arrangements texts
  * @{
  */
 #define GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP_TEXT "See getdns_context_set_dns_transport()"
@@ -180,15 +206,21 @@ typedef enum getdns_transport_t {
 */
 
 
+/**
+ * \defgroup transportlisttypes Transport list values
+ * @{
+ */
 /* Base transports for use in transport list */
 typedef enum getdns_transport_list_t {
 	GETDNS_TRANSPORT_UDP = 1200,
 	GETDNS_TRANSPORT_TCP = 1201,
 	GETDNS_TRANSPORT_TLS = 1202,
 } getdns_transport_list_t;
+/** @}
+ */
 
 /**
- * \defgroup Base transport texts
+ * \defgroup transportlisttypestext Transport list values texts
  * @{
  */
 #define GETDNS_TRANSPORT_UDP_TEXT "See getdns_context_set_dns_transport_list()"
@@ -198,16 +230,21 @@ typedef enum getdns_transport_list_t {
  */
 
 
-/* Suffix appending methods */
+/**
+ * \defgroup suffixappendtypes Suffix appending values
+ * @{
+ */
 typedef enum getdns_append_name_t {
 	GETDNS_APPEND_NAME_ALWAYS = 550,
 	GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE = 551,
 	GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE = 552,
 	GETDNS_APPEND_NAME_NEVER = 553
 } getdns_append_name_t;
+/** @}
+ */
 
 /**
- * \defgroup Suffix appending methods texts
+ * \defgroup suffixappendtypestext Suffix appending values texts
  * @{
  */
 #define GETDNS_APPEND_NAME_ALWAYS_TEXT "See getdns_context_set_append_name()"
@@ -218,6 +255,10 @@ typedef enum getdns_append_name_t {
  */
 
 
+/**
+* \defgroup contextcodetypes Context code values
+* @{
+*/
 /* Context codes */
 typedef enum getdns_context_code_t {
 	GETDNS_CONTEXT_CODE_NAMESPACES = 600,
@@ -239,9 +280,11 @@ typedef enum getdns_context_code_t {
 	GETDNS_CONTEXT_CODE_TIMEOUT = 616,
 	GETDNS_CONTEXT_CODE_IDLE_TIMEOUT = 617
 } getdns_context_code_t;
+/** @}
+ */
 
 /**
- * \defgroup Context codes texts
+ * \defgroup contextcodetypestext Context code values texts
  * @{
  */
 #define GETDNS_CONTEXT_CODE_NAMESPACES_TEXT "Change related to getdns_context_set_namespaces"
@@ -266,16 +309,21 @@ typedef enum getdns_context_code_t {
  */
 
 
-/* Callback Type Variables */
+/**
+ * \defgroup callbacktype Callback types
+ * @{
+ */
 typedef enum getdns_callback_type_t {
 	GETDNS_CALLBACK_COMPLETE = 700,
 	GETDNS_CALLBACK_CANCEL = 701,
 	GETDNS_CALLBACK_TIMEOUT = 702,
 	GETDNS_CALLBACK_ERROR = 703
 } getdns_callback_type_t;
+/** @}
+ */
 
 /**
- * \defgroup Callback type variables texts
+ * \defgroup callbacktypetext Callback types texts
  * @{
  */
 #define GETDNS_CALLBACK_COMPLETE_TEXT "The response has the requested data in it"
@@ -285,8 +333,9 @@ typedef enum getdns_callback_type_t {
 /** @}
  */
 
+
 /**
- * \defgroup nametype Types of name services
+ * \defgroup nametype Types of name services and texts
  * @{
  */
 #define GETDNS_NAMETYPE_DNS 800
@@ -296,8 +345,9 @@ typedef enum getdns_callback_type_t {
 /** @}
  */
 
+
 /**
- * \defgroup respstatus Status Codes for Responses
+ * \defgroup respstatus Status Codes for responses and text
  * @{
  */
 #define GETDNS_RESPSTATUS_GOOD 900
@@ -314,7 +364,7 @@ typedef enum getdns_callback_type_t {
  */
 
 /**
- * \defgroup extvals Values Associated With Extensions
+ * \defgroup extvals Values associated with extensions
  * @{
  */
 #define GETDNS_EXTENSION_TRUE  1000
@@ -325,7 +375,7 @@ typedef enum getdns_callback_type_t {
  */
 
 /**
- * \defgroup dnserrors Values Associated With DNS Errors Found By The API
+ * \defgroup dnserrors Values associated with DNS errors found by the API and text
  * @{
  */
 #define GETDNS_BAD_DNS_CNAME_IN_TARGET 1100
@@ -427,7 +477,7 @@ typedef enum getdns_callback_type_t {
  */
 
 /**
- * \defgroup rrclasses RR classes
+ * \defgroup rrclasses RR Classes
  * @{
  */
 #define GETDNS_RRCLASS_IN     1
@@ -479,6 +529,8 @@ typedef enum getdns_callback_type_t {
 
 typedef struct getdns_context getdns_context;
 typedef uint64_t getdns_transaction_t;
+
+
 /**
  * used to check data types within complex types (dict, list)
  */
@@ -505,6 +557,30 @@ typedef struct getdns_dict getdns_dict;
  */
 typedef struct getdns_list getdns_list;
 
+/* Specify the order of the following groups manually here so they appear in 
+   a better order in doxygen */
+
+/**
+ * \defgroup list_create getdns_list creation/destruction functions
+ * \defgroup getdns_list_set getdns_list_set functions
+ * \defgroup getdns_list_get_functions getdns_list_get functions
+ * \defgroup dict_create getdns_dict creation/destruction functions
+ * \defgroup getdns_dict_set getdns_dict_set functions
+ * \defgroup getdns_dict_get_functions getdns_dict_get functions
+ * \defgroup context_create getdns_context creation/destruction functions
+ * \defgroup context_set getdns_context_set functions
+ * \defgroup callbacks getdns_callback functions
+ * \defgroup funcs Asynchronous API functions
+ * \defgroup syncfuns Synchronous API functions that do not use callbacks
+ * \defgroup utils Utility functions
+ */
+
+
+/**
+ * \ingroup getdns_list_get_functions getdns_list_get functions
+ * @{
+ */
+
 /**
  * get the length of the specified list (returned in *answer)
  * @param list list of any of the supported data types
@@ -575,6 +651,14 @@ getdns_return_t getdns_list_get_bindata(const getdns_list *list, size_t index,
  */
 getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index,
     uint32_t * answer);
+/** @}
+ */
+
+
+/**
+ * \ingroup getdns_dict_get_functions getdns_dict_get functions
+ * @{
+ */
 
 /**
  * fetch a list of names from the dictionary, this list must be freed by the caller
@@ -641,6 +725,14 @@ getdns_return_t getdns_dict_get_bindata(const getdns_dict *dict,
  */
 getdns_return_t getdns_dict_get_int(const getdns_dict *dict,
     const char *name, uint32_t * answer);
+/** @}
+ */
+
+
+/**
+ * \ingroup list_create getdns_list creation/destruction functions
+ * @{
+ */
 
 /**
  * create a new list with no items
@@ -660,6 +752,7 @@ getdns_list *getdns_list_create_with_extended_memory_functions(
     void (*free) (void *userarg, void *)
 );
 
+
 /**
  * free memory allocated to the list (also frees all children of the list)
  * note that lists and bindata retrieved from the list via the getdns_list_get_*
@@ -668,6 +761,14 @@ getdns_list *getdns_list_create_with_extended_memory_functions(
  * unpleasant things will happen at run-time
  */
 void getdns_list_destroy(getdns_list *list);
+/** @}
+*/
+
+
+/**
+ * \ingroup getdns_list_set getdns_list_set functions
+ * @{
+ */
 
 /**
  * assign the child_dict to an item in a parent list, the parent list copies
@@ -710,6 +811,14 @@ getdns_return_t getdns_list_set_bindata(getdns_list *list, size_t index,
  */
 getdns_return_t getdns_list_set_int(getdns_list *list, size_t index,
     uint32_t child_uint32);
+/** @}
+ */
+
+
+/**
+ * \ingroup dict_create getdns_dict creation/destruction functions
+ * @{
+ */
 
 /**
  * create a new dictionary with no items
@@ -735,6 +844,14 @@ getdns_dict *getdns_dict_create_with_extended_memory_functions(
  * no longer be available (you are likely to experience bad things if you try)
  */
 void getdns_dict_destroy(getdns_dict *dict);
+/** @}
+*/
+
+
+/**
+ * \ingroup getdns_dict_set getdns_dict_set functions
+ * @{
+ */
 
 getdns_return_t getdns_dict_set_dict(getdns_dict *dict,
     const char *name, const getdns_dict *child_dict);
@@ -767,6 +884,9 @@ getdns_return_t getdns_dict_set_bindata(getdns_dict *dict,
  */
 getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name,
     uint32_t child_uint32);
+/** @}
+ */
+
 
 /**
  * remove the value associated with the specified name
@@ -777,14 +897,37 @@ getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name,
  */
 getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);
 
+
+/**
+ * \ingroup callbacks getdns_callback functions
+ * @{
+ */
+
 /* Callback arguments */
 typedef void (*getdns_callback_t) (getdns_context *context,
     getdns_callback_type_t callback_type,
     getdns_dict * response,
     void *userarg, getdns_transaction_t transaction_id);
+/** @}
+ */
 
-/* Function definitions */
 
+/**
+ * \ingroup funcs Asynchronous API functions
+ * @{
+ */
+
+/**
+ * retrieve general DNS data
+ * @param context pointer to a previously created context to be used for this call
+ * @param name the ASCII based domain name to lookup
+ * @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
+ * @param extensions dict data structures, NULL to use no extensions
+ * @param userarg void* returned to the callback  untouched
+ * @param[out] transaction_id id used to identify the callback, NULL is ignored
+ * @param callbackfn callback function defined by the application
+ * @return GETDNS_RETURN_GOOD on success
+ */
 getdns_return_t
 getdns_general(getdns_context *context,
     const char *name,
@@ -792,28 +935,92 @@ getdns_general(getdns_context *context,
     getdns_dict *extensions,
     void *userarg,
     getdns_transaction_t * transaction_id, getdns_callback_t callbackfn);
+
+/**
+ * retrieve address assigned to a DNS name
+ * @param context pointer to a previously created context to be used for this call
+ * @param name the ASCII based domain name to lookup
+ * @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
+ * @param extensions dict data structures, NULL to use no extensions
+ * @param userarg void* returned to the callback  untouched
+ * @param[out] transaction_id id used to identify the callback, NULL is ignored
+ * @param callbackfn callback function defined by the application
+ * @return GETDNS_RETURN_GOOD on success
+ */
 getdns_return_t
 getdns_address(getdns_context *context,
     const char *name,
     getdns_dict *extensions,
     void *userarg,
     getdns_transaction_t * transaction_id, getdns_callback_t callbackfn);
+
+/**
+ * retrieve hostname assigned to an IP address
+ * @param context pointer to a previously created context to be used for this call
+ * @param address the address to look up
+ * @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
+ * @param extensions dict data structures, NULL to use no extensions
+ * @param userarg void* returned to the callback  untouched
+ * @param[out] transaction_id id used to identify the callback, NULL is ignored
+ * @param callbackfn callback function defined by the application
+ * @return GETDNS_RETURN_GOOD on success
+ */
 getdns_return_t
 getdns_hostname(getdns_context *context,
     getdns_dict *address,
     getdns_dict *extensions,
     void *userarg,
     getdns_transaction_t * transaction_id, getdns_callback_t callbackfn);
+
+/**
+ * retrieve a service assigned to a DNS name
+ * @param context pointer to a previously created context to be used for this call
+ * @param name the ASCII based domain name to lookup
+ * @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
+ * @param extensions dict data structures, NULL to use no extensions
+ * @param userarg void* returned to the callback  untouched
+ * @param[out] transaction_id id used to identify the callback, NULL is ignored
+ * @param callbackfn callback function defined by the application
+ * @return GETDNS_RETURN_GOOD on success
+ */
 getdns_return_t
 getdns_service(getdns_context *context,
     const char *name,
     getdns_dict *extensions,
     void *userarg,
     getdns_transaction_t * transaction_id, getdns_callback_t callbackfn);
+/** @}
+ */
 
+
+/**
+ * \ingroup context_create getdns_context creation/destruction functions
+ * @{
+ */
+
+/**
+ * creates a new getdns context with default settings.
+ * If used multi-threaded, user must define appropriate OpenSSL callback locking functions
+ * (e.g. CRYPTO_THREADID_set_call) depending on the library version used.
+ * @param context context that can be used immediately with other API calls
+ * @param set_from_os select to use os defaults or to specify user defined values
+ * @return GETDNS_RETURN_GOOD on success
+*/
 getdns_return_t
 getdns_context_create(getdns_context ** context, int set_from_os);
 
+
+/**
+ * creates a new getdns context with default settings using custom memory functions.
+ * If used multi-threaded, user must define appropriate OpenSSL callback locking functions
+ * (e.g. CRYPTO_THREADID_set_call) depending on the library version used.
+ * @param context context that can be used immediately with other API calls
+ * @param set_from_os select to use os defaults or to specify user defined values
+ * @param malloc custom malloc function
+ * @param realloc custom realloc function
+ * @param malloc custom free function
+ * @return GETDNS_RETURN_GOOD on success
+*/
 getdns_return_t
 getdns_context_create_with_memory_functions(
     getdns_context ** context,
@@ -823,6 +1030,18 @@ getdns_context_create_with_memory_functions(
     void (*free) (void *)
 );
 
+
+/**
+ * creates a new getdns context with default settings using extended custom memory functions.
+ * If used multi-threaded, user must define appropriate OpenSSL callback locking functions
+ * (e.g. CRYPTO_THREADID_set_call) depending on the library version used.
+ * @param context context that can be used immediately with other API calls
+ * @param set_from_os select to use os defaults or to specify user defined values
+ * @param malloc custom malloc function
+ * @param realloc custom realloc function
+ * @param malloc custom free function
+ * @return GETDNS_RETURN_GOOD on success
+*/
 getdns_return_t
 getdns_context_create_with_extended_memory_functions(
     getdns_context **context,
@@ -834,13 +1053,23 @@ getdns_context_create_with_extended_memory_functions(
 );
 
 void getdns_context_destroy(getdns_context *context);
+/** @}
+ */
 
+
+/**
+* \ingroup callbacks getdns_callback functions
+* @{
+*/
 getdns_return_t
 getdns_cancel_callback(getdns_context *context,
     getdns_transaction_t transaction_id);
+/** @}
+ */
+
 
 /**
- * \defgroup syncfuns Synchronous API functions that do not use callbacks
+ * \ingroup syncfuns Synchronous API functions that do not use callbacks
  * These functions do not use callbacks, when the application calls one of these
  * functions the library retrieves all of the data before returning.  Return
  * values are exactly the same as if you had used a callback with the
@@ -871,7 +1100,6 @@ getdns_general_sync(getdns_context *context,
  * @param extensions dict data structures, NULL to use no extensions
  * @param response response
  * @return GETDNS_RETURN_GOOD on success
-
  */
 getdns_return_t
 getdns_address_sync(getdns_context *context,
@@ -910,6 +1138,11 @@ getdns_service_sync(getdns_context *context,
 /** @}
  */
 
+/**
+ * \ingroup utils Utility functions
+ * @{
+ */
+
 getdns_return_t
 getdns_convert_dns_name_to_fqdn(
     const getdns_bindata *dns_name_wire_fmt,
@@ -943,6 +1176,14 @@ char *getdns_pretty_print_dict(const getdns_dict *some_dict);
 char *getdns_display_ip_address(const getdns_bindata
     *bindata_of_ipv4_or_ipv6_address);
 
+/** @}
+ */
+
+
+/**
+ * \ingroup context_set getdns_context_set functions
+ * @{
+ */
 getdns_return_t
 getdns_context_set_context_update_callback(
   getdns_context *context,
@@ -1031,6 +1272,8 @@ getdns_context_set_extended_memory_functions(getdns_context *context,
     void *(*realloc) (void *userarg, void *ptr, size_t sz),
     void (*free) (void *userarg, void *ptr)
     );
+/** @}
+ */
 
 /* api information support */
 getdns_dict*

src/getdns/getdns_extra.h.in

@@ -426,7 +426,7 @@ typedef enum getdns_tls_authentication_t {
 #define GETDNS_AUTHENTICATION_HOSTNAME GETDNS_AUTHENTICATION_REQUIRED
 
 /**
-  * \defgroup Base authentication texts
+  * \defgroup authtext Authentication texts
   * @{
   */
 #define GETDNS_AUTHENTICATION_NONE_TEXT "See getdns_context_set_tls_authentication()"

src/types-internal.h

@@ -62,10 +62,7 @@ struct getdns_context;
 struct getdns_upstreams;
 struct getdns_upstream;
 
-/**
+/* String constants for internal use */
- * \defgroup strings String Constants
- * @{
- */
 #define GETDNS_STR_IPV4 "IPv4"
 #define GETDNS_STR_IPV6 "IPv6"
 #define GETDNS_STR_ADDRESS_TYPE "address_type"
@@ -119,8 +116,6 @@ struct getdns_upstream;
 #define GETDNS_TRANSPORTS_MAX 3
 #define GETDNS_UPSTREAM_TRANSPORTS 2
 
-/** @}
- */
 
 /* declarations */
 struct getdns_dns_req;