[5039] Comments for default parameters added.

src/bin/dhcp4/simple_parser4.cc

@@ -8,13 +8,29 @@
 #include <cc/data.h>
 #include <boost/foreach.hpp>
 
-using namespace std;
 using namespace isc::data;
 
 namespace isc {
 namespace dhcp {
+/// @brief This sets of arrays define the default values and
+///        values inherited (derived) between various scopes.
+///
+/// Each of those is documented in @file simple_parser4.cc. This
+/// is different than most other comments in Kea code. The reason
+/// for placing those in .cc rather than .h file is that it
+/// is expected to be one centralized place to look at for
+/// the default values. This is expected to be looked at also by
+/// people who are not skilled in C or C++, so they may be
+/// confused with the differences between declaration and defintion.
+/// As such, there's one file to look at that hopefully is readable
+/// without any C or C++ skills.
+///
+/// @{
 
-/// This table defines default values for option definitions in DHCPv4
+/// @brief This table defines default values for option definitions in DHCPv4.
+///
+/// Dhcp4 may contain an array called option-def that enumerates new option
+/// definitions. This array lists default values for those option definitions.
 const SimpleDefaults SimpleParser4::OPTION4_DEF_DEFAULTS = {
     { "record-types", Element::string,  ""},
     { "space",        Element::string,  "dhcp4"},
@@ -22,27 +38,44 @@ const SimpleDefaults SimpleParser4::OPTION4_DEF_DEFAULTS = {
     { "encapsulate",  Element::string,  "" }
 };
 
-/// This table defines default values for options in DHCPv4
+/// @brief This table defines default values for options in DHCPv4.
+///
+/// Dhcp4 usually contains option values (option-data) defined in global,
+/// subnet, class or host reservations scopes. This array lists default values
+/// for those option-data declarations.
 const SimpleDefaults SimpleParser4::OPTION4_DEFAULTS = {
     { "space",        Element::string,  "dhcp4"},
     { "csv-format",   Element::boolean, "true"},
     { "encapsulate",  Element::string,  "" }
 };
 
-/// This table defines default values for DHCPv4
+/// @brief This table defines default global values for DHCPv4
+///
+/// Some of the global parameters defined in the global scope (i.e. directly
+/// in Dhcp4) are optional. If not defined, the following values will be
+/// used.
 const SimpleDefaults SimpleParser4::GLOBAL4_DEFAULTS = {
     { "renew-timer",        Element::integer, "900" },
     { "rebind-timer",       Element::integer, "1800" },
     { "valid-lifetime",     Element::integer, "7200" }
 };
 
-/// This list defines parameters that can be inherited from the global
-/// scope to subnet6 scope.
+/// @brief List of parameters that can be inherited from the global to subnet4 scope.
+///
+/// Some parameters may be defined on both global (directly in Dhcp4) and
+/// subnet (Dhcp4/subnet4/...) scope. If not defined in the subnet scope,
+/// the value is being inherited (derived) from the global scope. This
+/// array lists all of such parameters.
 const ParamsList SimpleParser4::INHERIT_GLOBAL_TO_SUBNET4 = {
     "renew-timer",
     "rebind-timer",
     "valid-lifetime"
 };
+/// @}
+
+/// ---------------------------------------------------------------------------
+/// --- end of default values -------------------------------------------------
+/// ---------------------------------------------------------------------------
 
 size_t SimpleParser4::setAllDefaults(isc::data::ElementPtr global) {
     size_t cnt = 0;

src/bin/dhcp4/simple_parser4.h

@@ -12,6 +12,12 @@
 namespace isc {
 namespace dhcp {
 
+/// @brief SimpleParser specialized for DHCPv4
+///
+/// This class is a @ref isc::data::SimpleParser dedicated to DHCPv4 parser.
+/// In particular, it contains all the default values and names of the
+/// parameters that are to be derived (inherited) between scopes.
+/// For the actual values, see @file simple_parser4.cc
 class SimpleParser4 : public isc::data::SimpleParser {
 public:
     /// @brief Sets all defaults for DHCPv4 configuration
@@ -22,6 +28,7 @@ public:
     /// @return number of default values added
     static size_t setAllDefaults(isc::data::ElementPtr global);
 
+    // see simple_parser4.cc for comments for those parameters
     static const isc::data::SimpleDefaults OPTION4_DEF_DEFAULTS;
     static const isc::data::SimpleDefaults OPTION4_DEFAULTS;
     static const isc::data::SimpleDefaults GLOBAL4_DEFAULTS;

src/bin/dhcp6/simple_parser6.cc

@@ -8,13 +8,29 @@
 #include <cc/data.h>
 #include <boost/foreach.hpp>
 
-using namespace std;
 using namespace isc::data;
 
 namespace isc {
 namespace dhcp {
+/// @brief This sets of arrays define the default values and
+///        values inherited (derived) between various scopes.
+///
+/// Each of those is documented in @file simple_parser6.cc. This
+/// is different than most other comments in Kea code. The reason
+/// for placing those in .cc rather than .h file is that it
+/// is expected to be one centralized place to look at for
+/// the default values. This is expected to be looked at also by
+/// people who are not skilled in C or C++, so they may be
+/// confused with the differences between declaration and defintion.
+/// As such, there's one file to look at that hopefully is readable
+/// without any C or C++ skills.
+///
+/// @{
 
-/// This table defines default values for option definitions in DHCPv6
+/// @brief This table defines default values for option definitions in DHCPv6.
+///
+/// Dhcp6 may contain an array called option-def that enumerates new option
+/// definitions. This array lists default values for those option definitions.
 const SimpleDefaults SimpleParser6::OPTION6_DEF_DEFAULTS = {
     { "record-types", Element::string,  ""},
     { "space",        Element::string,  "dhcp6"},
@@ -22,14 +38,22 @@ const SimpleDefaults SimpleParser6::OPTION6_DEF_DEFAULTS = {
     { "encapsulate",  Element::string,  "" }
 };
 
-/// This table defines default values for options in DHCPv6
+/// @brief This table defines default values for options in DHCPv6.
+///
+/// Dhcp6 usually contains option values (option-data) defined in global,
+/// subnet, class or host reservations scopes. This array lists default values
+/// for those option-data declarations.
 const SimpleDefaults SimpleParser6::OPTION6_DEFAULTS = {
     { "space",        Element::string,  "dhcp6"},
     { "csv-format",   Element::boolean, "true"},
     { "encapsulate",  Element::string,  "" }
 };
 
-/// This table defines default values for both DHCPv4 and DHCPv6
+/// @brief This table defines default global values for DHCPv6
+///
+/// Some of the global parameters defined in the global scope (i.e. directly
+/// in Dhcp6) are optional. If not defined, the following values will be
+/// used.
 const SimpleDefaults SimpleParser6::GLOBAL6_DEFAULTS = {
     { "renew-timer",        Element::integer, "900" },
     { "rebind-timer",       Element::integer, "1800" },
@@ -37,15 +61,23 @@ const SimpleDefaults SimpleParser6::GLOBAL6_DEFAULTS = {
     { "valid-lifetime",     Element::integer, "7200" }
 };
 
-/// This list defines parameters that can be inherited from the global
-/// scope to subnet6 scope.
+/// @brief List of parameters that can be inherited from the global to subnet6 scope.
+///
+/// Some parameters may be defined on both global (directly in Dhcp6) and
+/// subnet (Dhcp6/subnet6/...) scope. If not defined in the subnet scope,
+/// the value is being inherited (derived) from the global scope. This
+/// array lists all of such parameters.
 const ParamsList SimpleParser6::INHERIT_GLOBAL_TO_SUBNET6 = {
     "renew-timer",
     "rebind-timer",
     "preferred-lifetime",
     "valid-lifetime"
 };
+/// @}
 
+/// ---------------------------------------------------------------------------
+/// --- end of default values -------------------------------------------------
+/// ---------------------------------------------------------------------------
 
 size_t SimpleParser6::setAllDefaults(isc::data::ElementPtr global) {
     size_t cnt = 0;

src/bin/dhcp6/simple_parser6.h

@@ -12,6 +12,12 @@
 namespace isc {
 namespace dhcp {
 
+/// @brief SimpleParser specialized for DHCPv6
+///
+/// This class is a @ref isc::data::SimpleParser dedicated to DHCPv6 parser.
+/// In particular, it contains all the default values and names of the
+/// parameters that are to be derived (inherited) between scopes.
+/// For the actual values, see @file simple_parser6.cc
 class SimpleParser6 : public isc::data::SimpleParser {
 public:
 
@@ -23,6 +29,7 @@ public:
     /// @return number of default values added
     static size_t setAllDefaults(isc::data::ElementPtr global);
 
+    // see simple_parser6.cc for comments for those parameters
     static const isc::data::SimpleDefaults OPTION6_DEF_DEFAULTS;
     static const isc::data::SimpleDefaults OPTION6_DEFAULTS;
     static const isc::data::SimpleDefaults GLOBAL6_DEFAULTS;