From a55a0a3b364c7c6bc9aa7485afefe2c811a5357f Mon Sep 17 00:00:00 2001
From: Guilherme Maciel Ferreira <guilherme.maciel.ferreira@gmail.com>
Date: Sat, 27 Aug 2011 12:07:48 -0300
Subject: [PATCH] Improved DnsResolver documentation

---
 src/dns/dnsresolver.cpp |   25 +++++++++++++++++++++----
 src/dns/dnsresolver.h   |    9 ++++++---
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/src/dns/dnsresolver.cpp b/src/dns/dnsresolver.cpp
index 865b1a2..332a190 100644
--- a/src/dns/dnsresolver.cpp
+++ b/src/dns/dnsresolver.cpp
@@ -44,6 +44,12 @@ using I2n::Logger::GlobalLogger;
 // DnsResolver
 //-----------------------------------------------------------------------------
 
+/**
+ * @brief Constructor.
+ *
+ * @param dns_address The DNS address to resolve.
+ * @param nameserver The server to consult about name resolution.
+ */
 DnsResolver::DnsResolver(
         const string &dns_address,
         const string &nameserver
@@ -54,13 +60,16 @@ DnsResolver::DnsResolver(
 {
 }
 
+/**
+ * @brief Destructor.
+ */
 DnsResolver::~DnsResolver()
 {
 }
 
 /**
- * @brief Check if hostname is already an IPv4 address.
- *            Will insert it into #ResolvedHostAddressList.
+ * @brief Check if hostname is already an IPv4 address. Will insert it into
+ * #ResolvedHostAddressList.
  *
  * @param host_dns_address
  * @return bool True if already an ip, false if not
@@ -141,7 +150,10 @@ bool DnsResolver::resolve()
 }
 
 /**
- * @return the amount of IPs resolved for the DNS.
+ * @brief Obtain the amount of IP addresses resolved for the host name provided
+ * to this object.
+ *
+ * @return The amount of IPs resolved for the DNS.
  */
 int DnsResolver::get_resolved_ip_count() const
 {
@@ -153,6 +165,9 @@ int DnsResolver::get_resolved_ip_count() const
 }
 
 /**
+ * @brief Obtain the next IP address resolved for the host name provided to
+ * this object.
+ *
  * @return the next IP string in the list of resolved IPs. When reach the last
  * IP, it goes back to first, like a circular buffer.
  */
@@ -175,7 +190,9 @@ string DnsResolver::get_next_ip()
 }
 
 /**
- * @return true if the last IPs resolved for the host have expired, thus
+ * @brief Check if the resolved IPs are still valid.
+ *
+ * @return @c true if the last IPs resolved for the host have expired, thus
  * requiring another query for up-to-date IPs.
  */
 bool DnsResolver::expired_resolved_ip()
diff --git a/src/dns/dnsresolver.h b/src/dns/dnsresolver.h
index 7ae8955..11c0b95 100644
--- a/src/dns/dnsresolver.h
+++ b/src/dns/dnsresolver.h
@@ -31,6 +31,9 @@ class HostAddress;
 // DnsResolver
 //-----------------------------------------------------------------------------
 
+/**
+ * @brief The class which provides Domain Name resolution to IP addresses.
+ */
 class DnsResolver
 {
 public:
@@ -58,11 +61,11 @@ private:
 
     bool handle_ip_address();
 private:
-    /// the list of IPs available to the host DNS
+    /// The list of IPs available to the host DNS.
     std::list<HostAddress> ResolvedHostAddressList;
-    /// the DNS of the host
+    /// The DNS of the host.
     const std::string HostDnsAddress;
-    /// the address of the server which can resolve the host address
+    /// The address of the server which can resolve the host address.
     const std::string NameServer;
 
 };
-- 
1.7.1