[2490] Improved comments in OptionDefinition class.

src/lib/dhcp/option_definition.cc

@@ -57,15 +57,23 @@ OptionDefinition::DataTypeUtil::getOptionDataType(const std::string& data_type)
 
 template<typename T>
 T OptionDefinition::DataTypeUtil::lexicalCastWithRangeCheck(const std::string& value_str) const {
+    // Lexical cast in case of our data types make sense only
+    // for uintX_t, intX_t and bool type.
     if (!OptionDataTypeTraits<T>::integer_type &&
         OptionDataTypeTraits<T>::type != OPT_BOOLEAN_TYPE) {
         isc_throw(BadDataTypeCast, "unable to do lexical cast to non-integer and"
                   << " non-boolean data type");
     }
+    // We use the 64-bit value here because it has greater range than
+    // any other type we use here and it allows to detect some out of
+    // bounds conditions e.g. negative value specified for uintX_t
+    // data type. Obviously if the value exceeds the limits of int64
+    // this function will not handle that properly.
     int64_t result = 0;
     try {
         result = boost::lexical_cast<int64_t>(value_str);
     } catch (const boost::bad_lexical_cast& ex) {
+        // Prepare error message here.
         std::string data_type_str = "boolean";
         if (OptionDataTypeTraits<T>::integer_type) {
             data_type_str = "integer";
@@ -73,6 +81,7 @@ T OptionDefinition::DataTypeUtil::lexicalCastWithRangeCheck(const std::string& v
         isc_throw(BadDataTypeCast, "unable to do lexical cast to " << data_type_str
                   << " data type for value " << value_str << ": " << ex.what());
     }
+    // Perform range checks for integer values only (exclude bool values).
     if (OptionDataTypeTraits<T>::integer_type) {
         if (result > numeric_limits<T>::max() ||
             result < numeric_limits<T>::min()) {
@@ -85,7 +94,8 @@ T OptionDefinition::DataTypeUtil::lexicalCastWithRangeCheck(const std::string& v
 }
 
 void
-OptionDefinition::DataTypeUtil::writeToBuffer(const std::string& value, uint16_t type,
+OptionDefinition::DataTypeUtil::writeToBuffer(const std::string& value,
+                                              const OptionDataType type,
                                               OptionBuffer& buf) {
     switch (type) {
     case OPT_BINARY_TYPE:

src/lib/dhcp/option_definition.h

@@ -152,10 +152,38 @@ private:
         /// @return option data type.
         OptionDataType getOptionDataType(const std::string& data_type_name);
 
+        /// @brief Perform lexical cast of the value and validate its range.
+        ///
+        /// This function performs lexical cast of a string value to integer
+        /// or boolean value and checks if the resulting value is within a
+        /// range of a target type. Note that range checks are not performed
+        /// on boolean values. The target type should be one of the supported
+        /// integer types or bool.
+        ///
+        /// @param value_str input value given as string.
+        /// @tparam T target type for lexical cast.
+        ///
+        /// @return cast value.
+        /// @throw BadDataTypeCast if cast was not successful.
         template<typename T>
         T lexicalCastWithRangeCheck(const std::string& value_str) const;
 
-        void writeToBuffer(const std::string& value, uint16_t type,
+        /// @brief Write the string value into the provided buffer.
+        ///
+        /// This method writes the given value to the specified buffer.
+        /// The provided string value may represent data of different types.
+        /// The actual data type is specified with the second argument.
+        /// Based on a value of this argument, this function will first
+        /// try to cast the string value to the particular data type and
+        /// if it is successful it will store the data in the buffer
+        /// in a binary format.
+        ///
+        /// @param value string representation of the value to be written.
+        /// @param type the actual data type to be stored.
+        /// @param [in, out] buf buffer where the value is to be stored.
+        ///
+        /// @throw BadDataTypeCast if data write was unsuccessful.
+        void writeToBuffer(const std::string& value, const OptionDataType type,
                            OptionBuffer& buf);
 
     private: