[#717,!417] Documented selectors for globals and options.

2 files changed, 147 insertions, 56 deletions

diff --git a/src/lib/dhcpsrv/config_backend_dhcp4.h b/src/lib/dhcpsrv/config_backend_dhcp4.h
index 8551d22351..188bcb7202 100644
--- a/src/lib/dhcpsrv/config_backend_dhcp4.h
+++ b/src/lib/dhcpsrv/config_backend_dhcp4.h
@@ -184,6 +184,9 @@ public:
 
     /// @brief Retrieves single option definition by code and space.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selector: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param code Code of the option to be retrieved.
     /// @param space Option space of the option to be retrieved.
@@ -194,6 +197,9 @@ public:
 
     /// @brief Retrieves all option definitions.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @return Collection of option definitions or empty collection if
     /// no option definition found.
@@ -202,6 +208,9 @@ public:
 
     /// @brief Retrieves option definitions modified after specified time.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param modification_time Lower bound option definition modification
     /// time.
@@ -213,6 +222,9 @@ public:
 
     /// @brief Retrieves single option by code and space.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selector: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param code Option code.
     /// @param space Option space.
@@ -224,6 +236,9 @@ public:
 
     /// @brief Retrieves all global options.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @return Collection of global options or empty collection if no
     /// option found.
@@ -232,6 +247,9 @@ public:
 
     /// @brief Retrieves options modified after specified time.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param selector Server selector.
     /// @param modification_time Lower bound option modification time.
     /// @return Collection of global options or empty collection if no
@@ -242,9 +260,8 @@ public:
 
     /// @brief Retrieves global parameter value.
     ///
-    /// Typically, the server selector used for this query should be set to
-    /// ONE. It is possible to use the MULTIPLE server selector but in that
-    /// case only the first found parameter is returned.
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selector: ANY, UNASSIGNED, MULTIPLE.
     ///
     /// @param selector Server selector.
     /// @param name Name of the global parameter to be retrieved.
@@ -256,31 +273,8 @@ public:
 
     /// @brief Retrieves all global parameters.
     ///
-    /// Using the server selector it is possible to fetch the parameters for
-    /// one or more servers. The following list describes what parameters are
-    /// returned depending on the server selector specified:
-    /// - ALL: only common parameters are returned which are associated with
-    ///   the logical server 'all'. No parameters associated with the explicit
-    ///   server tags are returned.
-    ///
-    /// - ONE: parameters used by the particular sever are returned. This includes
-    ///   parameters associated with the particular server (identified by tag)
-    ///   and parameters associated with the logical server 'all' when server
-    ///   specific parameters are not given. For example, if there is a
-    ///   renew-timer specified for 'server1' tag, different value of the
-    ///   renew-timer specified for 'all' servers and a rebind-timer specified
-    ///   for 'all' servers, the caller will receive renew-timer value associated
-    ///   with the server1 and the rebind-timer value associated with all servers,
-    ///   because there is no explicit rebind-timer specified for server1.
-    ///
-    /// - MULTIPLE: parameters used by multiple servers, but those associated
-    ///   with specific server tags take precedence over the values specified for
-    ///   'all' servers. This is similar to the case of ONE server described
-    ///   above. The effect of querying for parameters belonging to multiple
-    ///   servers is the same as issuing multiple queries with ONE server
-    ///   being selected multiple times.
-    ///
-    /// - UNASSIGNED: parameters not associated with any servers.
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
     ///
     /// @param selector Server selector.
     /// @return Collection of global parameters.
@@ -289,6 +283,9 @@ public:
 
     /// @brief Retrieves global parameters modified after specified time.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param selector Server selector.
     /// @param modification_time Modification time.
     /// @return Collection of modified global parameters.
@@ -298,6 +295,9 @@ public:
 
     /// @brief Retrieves the most recent audit entries.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param modification_time Timestamp being a lower limit for the returned
     /// result set, i.e. entries later than specified time are returned.
@@ -347,6 +347,9 @@ public:
 
     /// @brief Creates or updates an option definition.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param option_def Option definition to be added or updated.
     virtual void
@@ -355,6 +358,9 @@ public:
 
     /// @brief Creates or updates global option.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param option Option to be added or updated.
     virtual void
@@ -363,6 +369,9 @@ public:
 
     /// @brief Creates or updates shared network level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param selector Server selector.
     /// @param shared_network_name Name of a shared network to which option
     /// belongs.
@@ -374,6 +383,9 @@ public:
 
     /// @brief Creates or updates subnet level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param subnet_id Identifier of a subnet to which option belongs.
     /// @param option Option to be added or updated.
@@ -384,6 +396,9 @@ public:
 
     /// @brief Creates or updates pool level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param pool_start_address Lower bound address of the pool to which
     /// the option belongs.
@@ -398,6 +413,9 @@ public:
 
     /// @brief Creates or updates global parameter.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param value Value of the global parameter.
     virtual void
@@ -477,6 +495,9 @@ public:
 
     /// @brief Deletes option definition.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param code Code of the option to be deleted.
     /// @param space Option space of the option to be deleted.
@@ -487,6 +508,9 @@ public:
 
     /// @brief Deletes all option definitions.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @return Number of deleted option definitions.
     virtual uint64_t
@@ -494,6 +518,9 @@ public:
 
     /// @brief Deletes global option.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param code Code of the option to be deleted.
     /// @param space Option space of the option to be deleted.
@@ -504,6 +531,9 @@ public:
 
     /// @brief Deletes shared network level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param selector Server selector.
     /// @param shared_network_name Name of the shared network which option
     /// belongs to.
@@ -517,6 +547,9 @@ public:
 
     /// @brief Deletes subnet level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param subnet_id Identifier of the subnet to which deleted option
     /// belongs.
@@ -529,6 +562,9 @@ public:
 
     /// @brief Deletes pool level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param pool_start_address Lower bound address of the pool to which
     /// deleted option belongs.
@@ -546,6 +582,9 @@ public:
 
     /// @brief Deletes global parameter.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param name Name of the global parameter to be deleted.
     /// @return Number of deleted global parameters.
@@ -555,6 +594,9 @@ public:
 
     /// @brief Deletes all global parameters.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @return Number of deleted global parameters.
     virtual uint64_t
diff --git a/src/lib/dhcpsrv/config_backend_dhcp6.h b/src/lib/dhcpsrv/config_backend_dhcp6.h
index 2d88147bd2..24a69533b8 100644
--- a/src/lib/dhcpsrv/config_backend_dhcp6.h
+++ b/src/lib/dhcpsrv/config_backend_dhcp6.h
@@ -172,6 +172,9 @@ public:
 
     /// @brief Retrieves shared networks modified after specified time.
     ///
+    /// Allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    /// Not allowed server selector: ANY.
+    ///
     /// @param server_selector Server selector.
     /// @param modification_time Lower bound shared network modification time.
     /// @return Collection of shared network or empty collection if
@@ -182,6 +185,9 @@ public:
 
     /// @brief Retrieves single option definition by code and space.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selector: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param code Code of the option to be retrieved.
     /// @param space Option space of the option to be retrieved.
@@ -192,6 +198,9 @@ public:
 
     /// @brief Retrieves all option definitions.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @return Collection of option definitions or empty collection if
     /// no option definition found.
@@ -200,6 +209,9 @@ public:
 
     /// @brief Retrieves option definitions modified after specified time.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param modification_time Lower bound option definition modification
     /// time.
@@ -211,6 +223,9 @@ public:
 
     /// @brief Retrieves single option by code and space.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selector: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param code Option code.
     /// @param space Option space.
@@ -222,6 +237,9 @@ public:
 
     /// @brief Retrieves all global options.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @return Collection of global options or empty collection if no
     /// option found.
@@ -230,6 +248,9 @@ public:
 
     /// @brief Retrieves options modified after specified time.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param selector Server selector.
     /// @param modification_time Lower bound option modification time.
     /// @return Collection of global options or empty collection if no
@@ -240,9 +261,8 @@ public:
 
     /// @brief Retrieves global parameter value.
     ///
-    /// Typically, the server selector used for this query should be set to
-    /// ONE. It is possible to use the MULTIPLE server selector but in that
-    /// case only the first found parameter is returned.
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selector: ANY, UNASSIGNED, MULTIPLE.
     ///
     /// @param selector Server selector.
     /// @param name Name of the global parameter to be retrieved.
@@ -254,31 +274,8 @@ public:
 
     /// @brief Retrieves all global parameters.
     ///
-    /// Using the server selector it is possible to fetch the parameters for
-    /// one or more servers. The following list describes what parameters are
-    /// returned depending on the server selector specified:
-    /// - ALL: only common parameters are returned which are associated with
-    ///   the logical server 'all'. No parameters associated with the explicit
-    ///   server tags are returned.
-    ///
-    /// - ONE: parameters used by the particular sever are returned. This includes
-    ///   parameters associated with the particular server (identified by tag)
-    ///   and parameters associated with the logical server 'all' when server
-    ///   specific parameters are not given. For example, if there is a
-    ///   renew-timer specified for 'server1' tag, different value of the
-    ///   renew-timer specified for 'all' servers and a rebind-timer specified
-    ///   for 'all' servers, the caller will receive renew-timer value associated
-    ///   with the server1 and the rebind-timer value associated with all servers,
-    ///   because there is no explicit rebind-timer specified for server1.
-    ///
-    /// - MULTIPLE: parameters used by multiple servers, but those associated
-    ///   with specific server tags take precedence over the values specified for
-    ///   'all' servers. This is similar to the case of ONE server described
-    ///   above. The effect of querying for parameters belonging to multiple
-    ///   servers is the same as issuing multiple queries with ONE server
-    ///   being selected multiple times.
-    ///
-    /// - UNASSIGNED: parameters not associated with any servers.
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
     ///
     /// @param selector Server selector.
     /// @return Collection of global parameters.
@@ -287,6 +284,9 @@ public:
 
     /// @brief Retrieves global parameters modified after specified time.
     ///
+    /// Allowed server selectors: ALL, ONE, MULTIPLE.
+    /// Not allowed server selectors: UNASSIGNED, MULTIPLE.
+    ///
     /// @param selector Server selector.
     /// @param modification_time Modification time.
     /// @return Collection of modified global parameters.
@@ -296,6 +296,9 @@ public:
 
     /// @brief Retrieves the most recent audit entries.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param modification_time Timestamp being a lower limit for the returned
     /// result set, i.e. entries later than specified time are returned.
@@ -345,6 +348,9 @@ public:
 
     /// @brief Creates or updates an option definition.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param option_def Option definition to be added or updated.
     virtual void
@@ -353,6 +359,10 @@ public:
 
     /// @brief Creates or updates global option.
     ///
+
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param option Option to be added or updated.
     virtual void
@@ -361,6 +371,9 @@ public:
 
     /// @brief Creates or updates shared network level option.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param selector Server selector.
     /// @param shared_network_name Name of a shared network to which option
     /// belongs.
@@ -372,6 +385,9 @@ public:
 
     /// @brief Creates or updates subnet level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param subnet_id Identifier of a subnet to which option belongs.
     /// @param option Option to be added or updated.
@@ -382,6 +398,9 @@ public:
 
     /// @brief Creates or updates pool level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param pool_start_address Lower bound address of the pool to which
     /// the option belongs.
@@ -396,6 +415,9 @@ public:
 
     /// @brief Creates or updates prefix delegation pool level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param pd_pool_prefix Address part of the prefix of the prefix
     /// delegation pool to which the option belongs.
@@ -410,6 +432,9 @@ public:
 
     /// @brief Creates or updates global parameter.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param value Value of the global parameter.
     virtual void
@@ -489,6 +514,9 @@ public:
 
     /// @brief Deletes option definition.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param code Code of the option to be deleted.
     /// @param space Option space of the option to be deleted.
@@ -499,6 +527,9 @@ public:
 
     /// @brief Deletes all option definitions.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @return Number of deleted option definitions.
     virtual uint64_t
@@ -506,6 +537,9 @@ public:
 
     /// @brief Deletes global option.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param code Code of the option to be deleted.
     /// @param space Option space of the option to be deleted.
@@ -529,6 +563,9 @@ public:
 
     /// @brief Deletes subnet level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param subnet_id Identifier of the subnet to which deleted option
     /// belongs.
@@ -541,6 +578,9 @@ public:
 
     /// @brief Deletes pool level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param pool_start_address Lower bound address of the pool to which
     /// deleted option belongs.
@@ -558,6 +598,9 @@ public:
 
     /// @brief Deletes prefix delegation pool level option.
     ///
+    /// Allowed server selectors: ANY.
+    /// Not allowed server selectors: UNASSIGNED, ALL, ONE, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param pd_pool_prefix Address part of the prefix of the prefix
     /// delegation pool to which the deleted option belongs.
@@ -575,6 +618,9 @@ public:
 
     /// @brief Deletes global parameter.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @param name Name of the global parameter to be deleted.
     /// @return Number of deleted global parameters.
@@ -584,6 +630,9 @@ public:
 
     /// @brief Deletes all global parameters.
     ///
+    /// Allowed server selectors: ALL, ONE.
+    /// Not allowed server selectors: ANY, UNASSIGNED, MULTIPLE.
+    ///
     /// @param server_selector Server selector.
     /// @return Number of deleted global parameters.
     virtual uint64_t