From 54cd916b857b0067223309466943011c1b2976fc Mon Sep 17 00:00:00 2001
From: defanor <defanor@uberspace.net>
Date: Wed, 22 Sep 2021 22:29:00 +0300
Subject: Update doxygen docs

---
 src/rexmpp_dns.h | 51 +++++++++++++++++++++++++++++++++++++++++++++++----
 src/rexmpp_tls.h |  3 +++
 2 files changed, 50 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);
 
 
diff --git a/src/rexmpp_tls.h b/src/rexmpp_tls.h
index 2d54d1e..21e61f3 100644
--- a/src/rexmpp_tls.h
+++ b/src/rexmpp_tls.h
@@ -33,6 +33,9 @@ enum rexmpp_tls_err {
 
 typedef enum rexmpp_tls_err rexmpp_tls_err_t;
 
+/**
+   @brief TLS context.
+*/
 #if defined(USE_GNUTLS)
 #include <gnutls/gnutls.h>
 struct rexmpp_tls {
-- 
cgit v1.2.3