[2313] Improved comments for OptionSpace class.

src/lib/dhcpsrv/option_space.cc

@@ -21,6 +21,7 @@ namespace dhcp {
 
 OptionSpace::OptionSpace(const std::string& name, const bool vendor_space)
     : name_(name), vendor_space_(vendor_space) {
+    //  Check that provided option space name is valid.
     if (!validateName(name_)) {
         isc_throw(InvalidOptionSpace, "Invalid option space name "
                   << name_);
@@ -29,6 +30,8 @@ OptionSpace::OptionSpace(const std::string& name, const bool vendor_space)
 
 bool
 OptionSpace::validateName(const std::string& name) {
+    // Allowed digits are: lower or upper case letters, digits,
+    // underscores and dashes. Empty option spaces are not allowed.
     if (boost::algorithm::all(name, boost::is_from_range('a', 'z') ||
                               boost::is_from_range('A', 'Z') ||
                               boost::is_digit() ||

src/lib/dhcpsrv/option_space.h

@@ -56,6 +56,11 @@ public:
     /// @param name option space name.
     /// @param vendor_space boolean value that indicates that the object
     /// describes the vendor space.
+    ///
+    /// @throw isc::dhcp::InvalidOptionSpace if given option space name
+    /// contains invalid characters or is empty. This constructor uses
+    /// \ref validateName function to check that the specified name is
+    /// correct.
     OptionSpace(const std::string& name, const bool vendor_space = false);
 
     /// @brief Return option space name.
@@ -71,8 +76,8 @@ public:
 
     /// @brief Mark option space as vendor space or non-vendor space.
     ///
-    /// @param a boolean value indicating that this option space is
-    /// a vendor space (true) or non-vendor space (false).
+    /// @param vendor_space a boolean value indicating that this option
+    /// space is a vendor space (true) or non-vendor space (false).
     void setVendorSpace(const bool vendor_space) {
         vendor_space_ = vendor_space;
     }
@@ -80,10 +85,13 @@ public:
     /// @brief Checks that the provided option space name is valid.
     ///
     /// It is expected that option space name consists of upper or
-    /// lower case letters or digits. All other characters are
-    /// prohibited.
+    /// lower case letters or digits. Also, it may contain underscores
+    /// or dashes. Other characters are prohibited. The empty option
+    /// space names are invalid.
     ///
     /// @param name option space name to be validated.
+    ///
+    /// @return true if the option space is valid, else it returns false.
     static bool validateName(const std::string& name);
 
 private:

src/lib/dhcpsrv/tests/option_space_unittest.cc

@@ -83,6 +83,9 @@ TEST(OptionSpaceTest, validateName) {
                               '\\', '|', '<','>', ',', '.', '?', '~', '`' };
     for (int i = 0; i < sizeof(specials); ++i) {
         std::ostringstream stream;
+        // Concatenate valid option space name: "abc" with an invalid character.
+        // That way we get option space names like: "abc!", "abc$" etc. It is
+        // expected that the validating function fails form them.
         stream << "abc" << specials[i];
         EXPECT_FALSE(OptionSpace::validateName(stream.str()))
             << "Test failed for special character '" << specials[i] << "'.";