From: Marcin Siodelski <marcin@isc.org>
Date: Tue, 13 Sep 2016 09:40:43 +0000 (+0200)
Subject: [5005] Addressed review comments - generally fixing commentary.
X-Git-Tag: trac5006_base~18^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=796963d9ebaa9ccc0922e3b4591dd55c3f2f9f86;p=thirdparty%2Fkea.git

[5005] Addressed review comments - generally fixing commentary.
---

diff --git a/src/bin/dhcp4/dhcp4_messages.mes b/src/bin/dhcp4/dhcp4_messages.mes
index d2e1cc17cb..5cc2653508 100644
--- a/src/bin/dhcp4/dhcp4_messages.mes
+++ b/src/bin/dhcp4/dhcp4_messages.mes
@@ -601,7 +601,7 @@ transaction identification information. The second argument specifies
 the leased address.
 
 % DHCP4_RESERVED_HOSTNAME_ASSIGNED %1: server assigned reserved hostname %2
-This debug message is issued when the server found hostname reservation
+This debug message is issued when the server found a hostname reservation
 for a client and uses this reservation in a hostname option sent back
 to this client. The reserved hostname is qualified with a value
 of 'qualifying-suffix' parameter, if this parameter is specified.
diff --git a/src/bin/dhcp4/dhcp4_srv.cc b/src/bin/dhcp4/dhcp4_srv.cc
index 291d80de41..c88ad8a361 100644
--- a/src/bin/dhcp4/dhcp4_srv.cc
+++ b/src/bin/dhcp4/dhcp4_srv.cc
@@ -1410,8 +1410,6 @@ Dhcpv4Srv::processHostnameOption(Dhcpv4Exchange& ex) {
             .arg(opt_hostname->getValue());
     }
 
-    // Hold the pointer to the context. This makes calls to the members and
-    // functions shorter in terms of the number of characters.
     AllocEngine::ClientContext4Ptr ctx = ex.getContext();
 
     // Hostname reservations take precedence over any other configuration,
@@ -1430,9 +1428,9 @@ Dhcpv4Srv::processHostnameOption(Dhcpv4Exchange& ex) {
             OptionUint8ArrayPtr
                 option_prl = boost::dynamic_pointer_cast<OptionUint8Array>
                 (ex.getQuery()->getOption(DHO_DHCP_PARAMETER_REQUEST_LIST));
-            // PRL option exists, so check if the hostname option code is
-            // included in it.
             if (option_prl) {
+                // PRL option exists, so check if the hostname option code is
+                // included in it.
                 const std::vector<uint8_t>&
                     requested_opts = option_prl->getValues();
                 if (std::find(requested_opts.begin(), requested_opts.end(),
diff --git a/src/bin/dhcp4/dhcp4_srv.h b/src/bin/dhcp4/dhcp4_srv.h
index 859a5ef2a8..9c9582c62c 100644
--- a/src/bin/dhcp4/dhcp4_srv.h
+++ b/src/bin/dhcp4/dhcp4_srv.h
@@ -592,11 +592,32 @@ private:
 
     /// @brief Process Hostname %Option sent by a client.
     ///
-    /// This function is called by the @c Dhcpv4Srv::processClientName when
-    /// the client has sent the Hostname option in its message to the server.
-    /// It comprises the actual logic to parse the Hostname option and
-    /// prepare the Hostname option to be sent back to the client in the
-    /// server's response.
+    /// This method is called by the @c Dhcpv4Srv::processClientName to
+    /// create an instance of the Hostname option to be returned to the
+    /// client. If this instance is created it is included in the response
+    /// message within the @c Dhcpv4Exchange object passed as an argument.
+    ///
+    /// The Hostname option instance is created if the client has included
+    /// Hostname option in its query to the server or if the client has
+    /// included Hostname option code in the Parameter Request List option.
+    /// In the former case, the server can use the Hostname supplied by the
+    /// client or replace it with a new hostname, depending on the server's
+    /// configuration. A reserved hostname takes precedence over a hostname
+    /// supplied by the client or auto generated hostname.
+    ///
+    /// If the 'qualifying-suffix' parameter is specified, its value is used
+    /// to qualify a hostname. For example, if the host reservation contains
+    /// a hostname 'marcin-laptop', and the qualifying suffix is
+    /// 'example.isc.org', the hostname returned to the client will be
+    /// 'marcin-laptop.example.isc.org'. If the 'qualifying-suffix' is not
+    /// specified (empty), the reserved hostname is returned to the client
+    /// unqualified.
+    ///
+    /// The 'qualifying-suffix' value is also used to qualify the hostname
+    /// supplied by the client, when this hostname is unqualified,
+    /// e.g. 'laptop-x'. If the supplied hostname is qualified, e.g.
+    /// 'laptop-x.example.org', the qualifying suffix will not be appended
+    /// to it.
     ///
     /// @param ex The exchange holding both the client's message and the
     /// server's response.