1 files changed, 47 insertions, 4 deletions

diff --git a/src/rexmpp_dns.h b/src/rexmpp_dns.h
index 704cafb..6641238 100644
--- a/src/rexmpp_dns.h
+++ b/src/rexmpp_dns.h
@@ -1,9 +1,10 @@
 /**
    @file rexmpp_dns.h
-   @brief DNS helper functions
+   @brief DNS resolution
    @author defanor <defanor@uberspace.net>
    @date 2020
    @copyright MIT license.
+
 */
 
 
@@ -15,6 +16,9 @@
 
 #include "rexmpp.h"
 
+/**
+   @brief DNS context.
+*/
 #if defined(USE_UNBOUND)
 #include <unbound.h>
 struct rexmpp_dns_ctx {
@@ -42,12 +46,23 @@ struct rexmpp_dns_srv {
 
 typedef struct rexmpp_dns_srv rexmpp_dns_srv_t;
 
+/**
+   @brief DNS query result.
+*/
 struct rexmpp_dns_result {
+  /** @brief NULL-terminated array of data pointers. They contain
+      ::rexmpp_dns_srv for SRV lookups, host addresses for A and AAAA
+      ones. */
   void **data;
+  /** @brief An array of data structure lengths. */
   int *len;
+  /** @brief Whether the result was retrieved securely (that is,
+      verified with DNSSEC). */
   int secure;
 };
 
+typedef struct rexmpp_dns_result rexmpp_dns_result_t;
+
 /**
    @brief Parses an SRV DNS RR's RDATA.
    @param[in] in SRV record's RDATA.
@@ -58,21 +73,45 @@ struct rexmpp_dns_result {
 int
 rexmpp_parse_srv (char *in, int in_len, struct rexmpp_dns_srv *out);
 
-typedef struct rexmpp_dns_result rexmpp_dns_result_t;
-
-/* struct rexmpp_dns_result *rexmpp_dns_result_init (int len); */
+/**
+   @brief Frees a ::rexmpp_dns_result structure and its members.
+   @param[in] result A pointer to a ::rexmpp_dns_result structure.
+*/
 void rexmpp_dns_result_free (rexmpp_dns_result_t *result);
 
+/**
+   @brief Initializes a DNS resolver context.
+*/
 int rexmpp_dns_ctx_init (rexmpp_t *s);
+
+/**
+   @brief Cleans up the state that can be discarded between XMPP
+   connections, to be called from rexmpp_cleanup.
+*/
 void rexmpp_dns_ctx_cleanup (rexmpp_t *s);
+
+/**
+   @brief Deinitializes a DNS resolver context.
+*/
 void rexmpp_dns_ctx_deinit (rexmpp_t *s);
+
+/**
+   @brief Sets file descriptors to select/poll.
+*/
 int rexmpp_dns_fds (rexmpp_t *s, fd_set *read_fds, fd_set *write_fds);
+
+/**
+   @brief Reports timeouts.
+*/
 struct timeval * rexmpp_dns_timeout (rexmpp_t *s,
                                      struct timeval *max_tv,
                                      struct timeval *tv);
 
 typedef void (*dns_query_cb_t) (rexmpp_t *s, void *ptr, rexmpp_dns_result_t *result);
 
+/**
+   @brief Initiates a query.
+*/
 int rexmpp_dns_resolve (rexmpp_t *s,
                         const char *query,
                         int rrtype,
@@ -80,6 +119,10 @@ int rexmpp_dns_resolve (rexmpp_t *s,
                         void* ptr,
                         dns_query_cb_t callback);
 
+/**
+   @brief Processes active queries, should be called based on the
+   reported timeouts and file descriptors.
+*/
 int rexmpp_dns_process (rexmpp_t *s, fd_set *read_fds, fd_set *write_fds);