[5039] Doc updated, doxygen warnings removed.

src/bin/dhcp4/dhcp4.dox

@@ -24,6 +24,9 @@ component implementation.
 
 @section dhcpv4ConfigParser Configuration Parser in DHCPv4
 
+Note: parsers are currently being migrated to @ref isc::data::SimpleParser. See
+@ref ccSimpleParser page for details.
+
 The common configuration parsers for the DHCP servers are located in the
 src/lib/dhcpsrv/parsers/ directory. Parsers specific to the DHCPv4 component
 are located in the src/bin/dhcp4/json_config_parser.cc. These parsers derive

src/bin/dhcp6/dhcp6.dox

@@ -24,6 +24,9 @@ component implementation.
 
 @section dhcpv6ConfigParser Configuration Parsers in DHCPv6
 
+Note: parsers are currently being migrated to @ref isc::data::SimpleParser. See
+@ref ccSimpleParser page for details.
+
 The common configuration parsers for the DHCP servers are located in the
 src/lib/dhcpsrv/parsers/ directory. Parsers specific to the DHCPv6 component
 are located in the src/bin/dhcp6/json_config_parser.cc. These parsers derive

src/lib/cc/Makefile.am

@@ -19,4 +19,6 @@ libkea_cc_la_LDFLAGS = -no-undefined -version-info 1:0:0
 libkea_cc_includedir = $(pkgincludedir)/cc
 libkea_cc_include_HEADERS = data.h
 
+EXTRA_DIST = cc.dox
+
 CLEANFILES = *.gcno *.gcda

src/lib/cc/cc.dox

@@ -0,0 +1,99 @@
+// Copyright (C) 2016 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libcc libcc - Kea configuration commands library
+
+@section ccSimpleParser Simple JSON Parser
+
+Since the early beginnings, our configuration parsing code was a mess. It
+started back in 2011 when Tomek joined ISC recently and was told to implement
+Kea configuration handling in similar way as DNS Auth module. The code grew
+over time (DHCP configuration is significantly more complex than DNS, with
+more interdependent values) and as of Kea 1.1 release it became very difficult
+to manage. The decision has been made to significantly refactor or even
+partially rewrite the parser code. The design for this effort is documented
+here: http://kea.isc.org/wiki/SimpleParser It discusses the original issues
+and the proposed architecture.
+
+There are several aspects of this new approach. The base class for all parsers
+is @ref isc::data::SimpleParser. It simplifies the parsers based on
+@ref isc::dhcp::DhcpConfigParser by rejecting the
+concept of build/commit phases. Instead, there should be a single method
+called parse that takes ConstElementPtr as a single parameter (that's the
+JSON structures to be parsed) and returns the config structure to be used
+in CfgMgr. An example of such a method can be the following:
+
+@code
+std::pair<OptionDescriptor, std::string>
+OptionDataParser::parse(isc::data::ConstElementPtr single_option)
+@endcode
+
+Since each derived class will have the same parameter, but a different return
+type, it's not possible to use virtual methods mechanism. That's perfectly
+ok, though, as there is only a single instance of the class needed to parse
+arbitrary number of parameters of the same type. There is no need to
+keep pointers to the parser object. As such there's fewer incentives to have
+one generic way to handle all parsers.
+
+@subsection ccSimpleParserDefaults Default values in Simple Parser
+
+Another simplification comes from the fact that almost all parameters
+are mandatory in SimpleParser. One source of complexities in the old
+parser was the necessity to deal with optional parameters. Simple
+parser deals with that by explicitly requiring the input structure to
+have all parameters filled. Obviously, it's not feasible to expect
+everyone to always specify all parameters, therefore there's an easy
+way to fill missing parameters with their default values. There are
+several methods to do this, but the most generic one is:
+
+@code
+static size_t
+isc::data::SimpleParser::setDefaults(isc::data::ElementPtr scope,
+                                     const SimpleDefaults& default_values);
+@endcode
+
+It takes a pointer to element to be filled with default values and
+vector of default values. Having those values specified in a single
+place in a way that can easily be read even by non-programmers is a
+big advantage of this approach. Here's an example from simple_parser.cc file:
+
+@code
+/// This table defines default values for option definitions in DHCPv6
+const SimpleDefaults OPTION6_DEF_DEFAULTS = {
+    { "record-types", Element::string,  ""},
+    { "space",        Element::string,  "dhcp6"},
+    { "array",        Element::boolean, "false"},
+    { "encapsulate",  Element::string,  "" }
+};
+@endcode
+
+This array (which technically is implemented as a vector and
+initialized the C++11 way) can be passed to the aforementioned
+setDefaults. That code will iterate over all default values and see if
+there are explicit values provided. If not, the gaps will be filled
+with default values. There are also convenience methods specified for
+filling in option data defaults, option definition defaults and
+setAllDefaults that sets all defaults (starts with global, but then
+walks down the Element tree and fills defaults in subsequent scopes).
+
+@subsection ccSimpleParserInherits Inheriting parameters between scopes
+
+SimpleParser provides a mechanism to inherit parameters between scopes,
+e.g. to inherit global parameters in the subnet scope if more specific
+values are not defined in the subnet scope. This is achieved by calling
+@code
+static size_t SimpleParser::deriveParams(isc::data::ConstElementPtr parent,
+                                         isc::data::ElementPtr child,
+                                         const ParamsList& params);
+
+@endcode
+
+ParamsList is a simple vector<string>. There will be more specific
+methods implemented in the future, but for the time being only
+@ref isc::data::SimpleParser::deriveParams is implemented.
+
+*/

src/lib/cc/simple_parser.h

@@ -33,7 +33,8 @@ typedef std::vector<std::string> ParamsList;
 
 /// @brief A simple parser
 ///
-/// This class is intended to be a simpler replacement for @ref DhcpConfigParser.
+/// This class is intended to be a simpler replacement for
+/// @ref isc::dhcp::DhcpConfigParser.
 /// The simplification comes from several factors:
 /// - no build/commit nonsense. There's a single step:
 ///   CfgStorage parse(ConstElementPtr json)
@@ -83,6 +84,15 @@ class SimpleParser {
     static size_t setDefaults(isc::data::ElementPtr scope,
                               const SimpleDefaults& default_values);
 
+    /// @brief Sets the default values for all entries in a list
+    ///
+    /// This is a simple utility method that iterates over all
+    /// parameters in a list and calls setDefaults for each
+    /// entry.
+    ///
+    /// @param list list to be iterated over
+    /// @param default_values list of default values
+    /// @return number of parameters inserted
     static size_t setListDefaults(isc::data::ElementPtr list,
                                   const SimpleDefaults& default_values);
 

src/lib/dhcpsrv/libdhcpsrv.dox

@@ -476,92 +476,5 @@ is used by DHCPv4 and DHCPv6 components.
 
 DHCPv4-over-DHCPv6 which are relayed by a DHCPv6 relay are not yet supported.
 
-@section dhcp6SimpleParser Simple JSON Parser
-
-Since the early beginnings, our configuration parsing code was a mess. It
-started back in 2011 when Tomek joined ISC recently and was told to implement
-Kea configuration handling in similar way as DNS Auth module. The code grew
-over time (DHCP configuration is significantly more complex than DNS, with
-more interdependent values) and as of Kea 1.1 release it became very difficult
-to manage. The decision has been made to significantly refactor or even
-partially rewrite the parser code. The design for this effort is documented
-here: http://kea.isc.org/wiki/SimpleParser It discusses the original issues
-and the proposed architecture.
-
-There are several aspects of this new approach. The base class for all parsers
-is @ref isc::dhcp::SimpleParser. It simplifies the parser be rejecting the
-concept of build/commit phases. Instead, there should be a single method
-called parse that takes ConstElementPtr as a single parameter (that's the
-JSON structures to be parsed) and returns the config structure to be used
-in CfgMgr. An example of such a method can be the following:
-
-@code
-std::pair<OptionDescriptor, std::string>
-OptionDataParser::parse(isc::data::ConstElementPtr single_option)
-@endcode
-
-Since each derived class will have the same parameter, but a different return
-type, it's not possible to use virtual methods mechanism. That's perfectly
-ok, though, as there is only a single instance of the class needed to parse
-arbitrary number of parameters of the same type, so there is no need to
-keep pointers to the parser object. As such there's fewer incentives to have
-one generic way to handle all parsers.
-
-@subsection dhcp6SimpleParserDefaults Default values in Simple Parser
-
-Another simplification comes from the fact that almost all parameters
-are mandatory in SimpleParser. One source of complexities in the old
-parser was the necessity to deal with optional parameters. Simple
-parser deals with that by explicitly requiring the input structure to
-have all parameters filled. Obviously, it's not feasible to expect
-everyone to always specify all parameters, therefore there's an easy
-way to fill missing parameters with their default values. There are
-several methods to do this, but the most generic one is:
-
-@code
-static size_t
-isc::dhcp::SimpleParser::setDefaults(isc::data::ElementPtr scope,
-                                     const SimpleDefaults& default_values);
-@endcode
-
-It takes a pointer to element to be filled with default values and
-vector of default values. Having those values specified in a single
-place in a way that can easily be read even by non-programmers is a
-big advantage of this approach. Here's an example from simple_parser.cc file:
-
-@code
-/// This table defines default values for option definitions in DHCPv6
-const SimpleDefaults OPTION6_DEF_DEFAULTS = {
-    { "record-types", Element::string,  ""},
-    { "space",        Element::string,  "dhcp6"},
-    { "array",        Element::boolean, "false"},
-    { "encapsulate",  Element::string,  "" }
-};
-@endcode
-
-This array (which technically is implemented as a vector and
-initialized the C++11 way) can be passed to the aforementioned
-setDefaults. That code will iterate over all default values and see if
-there are explicit values provided. If not, the gaps will be filled
-with default values. There are also convenience methods specified for
-filling in option data defaults, option definition defaults and
-setAllDefaults that sets all defaults (starts with global, but then
-walks down the Element tree and fills defaults in subsequent scopes).
-
-@subsection dhcp6SimpleParserInherits Inheriting parameters between scopes
-
-SimpleParser provides a mechanism to inherit parameters between scopes,
-e.g. to inherit global parameters in the subnet scope if more specific
-values are not defined in the subnet scope. This is achieved by calling
-@code
-static size_t SimpleParser::deriveParams(isc::data::ConstElementPtr parent,
-                                         isc::data::ElementPtr child,
-                                         const ParamsList& params);
-
-@endcode
-
-ParamsList is a simple vector<string>. There will be more specific
-methods implemented in the future, but for the time being only
-@ref isc::dhcp::SimpleParser::inheritGlobalToSubnet is implemented.
 
 */

src/lib/dhcpsrv/parsers/dhcp_parsers.h

@@ -552,7 +552,7 @@ public:
     ///
     /// Note: ElementPtr is expected to contain all fields. If your
     /// ElementPtr does not have them, please use
-    /// @ref SimpleParser::setOptionDefaults to fill the missing fields
+    /// @ref isc::data::SimpleParser::setDefaults to fill the missing fields
     /// with default values.
     ///
     /// @param single_option ElementPtr containing option defintion