[1955] Miscellaneous corrections to comments.

tests/tools/perfdhcp/perf_pkt4.h

@@ -26,24 +26,24 @@ namespace perfdhcp {
 
 /// \brief PerfPkt4 (DHCPv4 packet)
 ///
-/// This class extends functionality of \ref isc::dhcp::Pkt4 by
-/// adding ability to specify options offset in DHCP message
-/// and override options' contents.
-/// This is in particular useful when we create packet object using
-/// template file (do not build it dynamically). Client class
-/// should read data from template file and pass data to this class
-/// as buffer.
-/// Contents of such packet can be later partially replaced: preciselly
-/// selected options and transaction id can be replaced.
-/// Transaction id and its offset in template file is passed via
-/// constructor.
-/// In order to replace contents of options client class has to
-/// create collection of \ref LocalizedOption by adding them using
+/// This class extends the functionality of \ref isc::dhcp::Pkt4 by adding the
+/// ability to specify an options offset in the DHCP message and to override
+/// options' contents.  This is particularly useful when we create a packet
+/// object using a template file (i.e. do not build it dynamically). The client
+/// class should read data from the template file and pass it to this class in
+/// a buffer.
+///
+/// The contents of such a packet can be later partially replaced, notably the
+/// selected options and the transaction ID.  (The transaction ID and its
+/// offset in the template file are passed via the constructor.)
+///
+/// In order to replace contents of the options, the client class has to
+/// create a collection of \ref LocalizedOption, adding them using
 /// \ref dhcp::Pkt4::addOption.
 ///
-/// \note: if you don't use template files simply use constructors
+/// \note If you don't use template files simply use constructors
 /// inherited from parent class and isc::dhcp::Option type instead
-///
+
 class PerfPkt4 : public dhcp::Pkt4 {
 public:
 
@@ -52,7 +52,7 @@ public:
 
     /// \brief Constructor, used for outgoing and incoming messages
     ///
-    /// This constructor initializes transaction id and
+    /// This constructor initializes the transaction ID and
     /// transaction id offset of the packet with default
     /// values.
     ///
@@ -62,10 +62,10 @@ public:
 
     /// \brief Constructor, used for outgoing DHCP messages.
     ///
-    /// Creates new DHCPv4 message using provided buffer.
-    /// Transaction id and its offset are specified via this
-    /// constructor. Transaction id is stored in outgoing message
-    /// when client class calls \ref PerfPkt4::rawPack.
+    /// Creates new DHCPv4 message using the provided buffer.  The
+    /// transaction ID and its offset are specified via this
+    /// constructor. The transaction ID is stored in the outgoing message
+    /// when the client class calls \ref PerfPkt4::rawPack.
     ///
     /// \note This constructor should be used only for outgoing
     /// messages that are created from template files.
@@ -82,21 +82,21 @@ public:
 
     /// Constructor, used for incoming DHCP messages.
     ///
-    /// Creates new DHCPv4 message using provided buffer.
-    /// Client class may indicate which options are to be read
-    /// from the buffer. Such options should be added to
-    /// options collection using dhcp::Pkt4::addOption. Such
+    /// Creates new DHCPv4 message using the provided buffer.
+    /// The client class may indicate which options are to be read
+    /// from the buffer. Such options should be added to the
+    /// options collection using \ref dhcp::Pkt4::addOption: these
     /// options should be of \ref LocalizedOption class.
     ///
-    /// Transaction id offset points to location where
-    /// transaction id field is stored. The transaction id will
-    /// be read from this location when PerfPkt4::rawUnpack is
+    /// The transaction ID offset points to the location where the
+    /// transaction ID field is stored. The transaction ID will
+    /// be read from this location when \ref PerfPkt4::rawUnpack is
     /// called. The transid_ class member will be updated accordingly.
     ///
-    /// \note use this constructor only in case you want to create
-    /// incoming DHCPv4 object from the raw buffer
-    /// and you know options offsets. Options offsets are
-    /// specified from perfdhcp command line by the user.
+    /// \note Use this constructor only in the case where you want to create
+    /// an incoming DHCPv4 object from the raw buffer
+    /// and you know the options offsets. The options offsets are
+    /// specified on the perfdhcp command line by the user.
     ///
     /// \param buf pointer to a buffer of received packet content.
     /// \param len size of buffer of packet content.
@@ -107,33 +107,33 @@ public:
 
     /// \brief Returns transaction id offset in packet buffer
     ///
-    /// return transaction id offset in packet buffer
+    /// \return Transaction ID offset in packet buffer
     size_t getTransIdOffset() const { return transid_offset_; };
 
     /// \brief Prepares on-wire format from raw buffer.
     ///
-    /// The method copies buffer provided in constructor to
-    /// output buffer and replaces transaction id and selected
+    /// The method copies the buffer provided in the constructor to the
+    /// output buffer and replaces the transaction ID and selected
     /// options with new data.
     ///
-    /// \note: Use this method to prepare on-wire DHCPv4 message
+    /// \note Use this method to prepare an on-wire DHCPv4 message
     /// when you use template packets that require replacement
     /// of selected options' contents before sending.
     ///
-    /// \return false, id pack operation failed.
+    /// \return false ID pack operation failed.
     bool rawPack();
 
     /// \brief Handles limited binary packet parsing for packets with
-    /// custom offsets of options and transaction id
+    /// custom offsets of options and transaction ID
     ///
-    /// Function handles parsing of packets that have custom offsets
-    /// of options or transaction id. Use
+    /// This method handles the parsing of packets that have custom offsets
+    /// of options or transaction ID. Use
     /// \ref isc::dhcp::Pkt4::addOption to specify which options to parse.
-    /// Options should be of the: isc::perfdhcp::LocalizedOption
+    /// Options should be of the \ref isc::perfdhcp::LocalizedOption
     /// type with offset values provided. Each added option will
     /// be updated with actual data read from the binary packet buffer.
     ///
-    /// \return false, if unpack operation failed.
+    /// \return false If unpack operation failed.
     bool rawUnpack();
 
 private:

tests/tools/perfdhcp/perf_pkt6.h

@@ -26,24 +26,24 @@ namespace perfdhcp {
 
 /// \brief PerfPkt6 (DHCPv6 packet)
 ///
-/// This class extends functionality of \ref isc::dhcp::Pkt6 by
-/// adding ability to specify options offset in DHCP message
-/// and override options' contents.
-/// This is in particular useful when we create packet object using
-/// template file (do not build it dynamically). Client class
-/// should read data from template file and pass data to this class
-/// as buffer.
-/// Contents of such packet can be later partially replaced: preciselly
-/// selected options and transaction id can be replaced.
-/// Transaction id and its offset in template file is passed via
-/// constructor.
-/// In order to replace contents of options client class has to
-/// create collection of \ref LocalizedOption by adding them using
-/// \ref dhcp::Pkt6::addOption.
+/// This class extends the functionality of \ref isc::dhcp::Pkt6 by
+/// adding the ability to specify an options offset in the DHCP message
+/// and so override the options' contents. This is particularly useful when we
+/// create a packet object using a template file (i.e. do not build it
+/// dynamically). The client class should read the data from the template file
+/// and pass it to this class as a buffer.
+///
+/// The contents of such packet can be later partially replaced: in particular,
+/// selected options and the transaction ID can be altered. (The transaction
+/// ID and its offset in the template file is passed via the constructor.)
 ///
-/// \note: if you don't use template files simply use constructors
-/// inherited from parent class and isc::dhcp::Option type instead
+/// In order to replace the contents of options, the client class has to
+/// create a collection of \ref LocalizedOption by adding them using
+/// \ref dhcp::Pkt6::addOption.
 ///
+/// \note If you don't use template files, simply use constructors
+/// inherited from parent class and the \ref isc::dhcp::Option type instead.
+
 class PerfPkt6 : public dhcp::Pkt6 {
 public:
 
@@ -52,8 +52,8 @@ public:
 
     /// \brief Constructor, used for outgoing and incoming messages
     ///
-    /// This constructor initializes transaction id and
-    /// transaction id offset of the packet with default
+    /// This constructor initializes the transaction ID and the
+    /// transaction ID offset of the packet with default
     /// values.
     ///
     /// \param buf buffer holding contents of the message.
@@ -62,9 +62,9 @@ public:
 
     /// \brief Constructor, used for outgoing DHCP messages.
     ///
-    /// Creates new DHCPv6 message using provided buffer.
-    /// Transaction id and its offset are specified via this
-    /// constructor. Transaction id is stored in outgoing message
+    /// Creates a new DHCPv6 message using the provided buffer.
+    /// The transaction ID and its offset are specified via this
+    /// constructor. The transaction ID is stored in outgoing message
     /// when client class calls \ref PerfPkt6::rawPack.
     ///
     /// \note This constructor should be used only for outgoing
@@ -82,21 +82,21 @@ public:
 
     /// Constructor, used for incoming DHCP messages.
     ///
-    /// Creates new DHCPv6 message using provided buffer.
-    /// Client class may indicate which options are to be read
-    /// from the buffer. Such options should be added to
-    /// options collection using dhcp::Pkt4::addOption. Such
+    /// Creates a new DHCPv6 message using the provided buffer. The
+    /// client class may indicate which options are to be read
+    /// from the buffer. Such options should be added to the
+    /// options collection using \ref dhcp::Pkt4::addOption. The
     /// options should be of \ref LocalizedOption class.
     ///
-    /// Transaction id offset points to location where
-    /// transaction id field is stored. The transaction id will
-    /// be read from this location when PerfPkt4::rawUnpack is
+    /// The transaction ID offset points to location where the
+    /// transaction ID field is stored. The transaction ID will
+    /// be read from this location when \ref PerfPkt4::rawUnpack is
     /// called. The transid_ class member will be updated accordingly.
     ///
-    /// \note use this constructor only in case you want to create
+    /// \note Use this constructor only in the case where you want to create
     /// incoming DHCPv4 object from the raw buffer
-    /// and you know options offsets. Options offsets are
-    /// specified from perfdhcp command line by the user.
+    /// and you know the options offsets. Options offsets are
+    /// specified on the perfdhcp command line by the user.
     ///
     /// \param buf pointer to a buffer of received packet content.
     /// \param len size of buffer of packet content.
@@ -107,33 +107,33 @@ public:
 
     /// \brief Returns transaction id offset in packet buffer
     ///
-    /// return transaction id offset in packet buffer
+    /// \return Transaction ID offset in the packet buffer.
     size_t getTransIdOffset() const { return transid_offset_; };
 
-    /// \brief Prepares on-wire format from raw buffer.
+    /// \brief Prepares on-wire format from raw buffer
     ///
-    /// The method copies buffer provided in constructor to
-    /// output buffer and replaces transaction id and selected
+    /// The method copies the buffer provided in constructor to the
+    /// output buffer and replaces the transaction ID and selected
     /// options with new data.
     ///
-    /// \note: Use this method to prepare on-wire DHCPv6 message
+    /// \note Use this method to prepare an on-wire DHCPv6 message
     /// when you use template packets that require replacement
     /// of selected options' contents before sending.
     ///
-    /// \return false, id pack operation failed.
+    /// \return false ID pack operation failed.
     bool rawPack();
 
     /// \brief Handles limited binary packet parsing for packets with
     /// custom offsets of options and transaction id
     ///
-    /// Function handles parsing of packets that have custom offsets
-    /// of options or transaction id. Use
+    /// This methoid handles the parsing of packets that have custom offsets
+    /// of options or transaction ID. Use
     /// \ref isc::dhcp::Pkt4::addOption to specify which options to parse.
-    /// Options should be of the: isc::perfdhcp::LocalizedOption
+    /// Options should be of the \ref isc::perfdhcp::LocalizedOption
     /// type with offset values provided. Each added option will
     /// be updated with actual data read from the binary packet buffer.
     ///
-    /// \return false, if unpack operation failed.
+    /// \return false if unpack operation failed.
     bool rawUnpack();
 
 private:

tests/tools/perfdhcp/pkt_transform.cc

@@ -105,7 +105,7 @@ PktTransform::unpack(const Option::Universe universe,
             & 0xFFFFFF;
     } else {
         transid = ((in_buffer[transid_offset] << 24) +
-                   (in_buffer[transid_offset +1 ] << 16) +
+                   (in_buffer[transid_offset + 1] << 16) +
                    (in_buffer[transid_offset + 2] << 8) +
                    (in_buffer[transid_offset + 3]));
     }

tests/tools/perfdhcp/pkt_transform.h

@@ -24,45 +24,44 @@ namespace perfdhcp {
 
 /// \brief Read and write raw data to DHCP packets.
 ///
-/// This class provides static functions to read raw
-/// data from packet buffer and write raw data to packet
-/// buffer. When reading data with unpack() method, the
-/// corresponding options objects are updated.
-/// When writing to the packet buffer with pack(),
-/// options objects carry input data to be written.
+/// This class provides static functions to read/write raw data from/to the
+/// packet buffer. When reading data with the unpack() method, the
+/// corresponding options objects are updated.  When writing to the packet
+/// buffer with pack(), options objects carry input data to be written.
+///
 /// This class is used both by \ref PerfPkt4 and
 /// \ref PerfPkt6 classes in case DHCP packets are created
 /// from template files. In this case, some of the template
-/// packet's options are replaced before sending it to
-/// server. Offset of specific options are provided from
-/// command line by perfdhcp tool user and passed in
+/// packet's options are replaced before sending it to the
+/// server. Offset of specific options are provided from the
+/// command line by the perfdhcp tool user, and passed in an
 /// options collection.
 class PktTransform {
 public:
 
     /// \brief Prepares on-wire format from raw buffer.
     ///
-    /// The method copies input buffer and options contents
-    /// to output buffer. Input buffer must contain whole
+    /// The method copies the input buffer and options contents
+    /// to the output buffer. The input buffer must contain whole
     /// initial packet data. Parts of this data will be
-    /// overriden by options data specified in options
+    /// overriden by options data specified in an options
     /// collection. Such options must have their offsets within
     /// a packet specified (see \ref LocalizedOption to find out
     /// how to specify options offset).
     ///
-    /// \note Specified options must fit into size of the
-    /// initial packet data. Call to this function will fail
-    /// if option's offset + its size is beyond packet's size.
+    /// \note The specified options must fit into the size of the
+    /// initial packet data. A call to this method will fail
+    /// if the option's offset + its size is beyond the packet's size.
     ///
-    /// \param universe universe used, V4 or V6
-    /// \param in_buffer input buffer holiding intial packet
+    /// \param universe Universe used, V4 or V6
+    /// \param in_buffer Input buffer holding intial packet
     /// data, this can be directly read from template file
-    /// \param options options collection with offsets
-    /// \param transid_offset offset of transaction id in a packet,
-    /// transatcion id will be written to output buffer at this
+    /// \param options Options collection with offsets
+    /// \param transid_Offset offset of transaction id in a packet,
+    /// transaction ID will be written to output buffer at this
     /// offset
-    /// \param transid transaction id value
-    /// \param out_buffer output buffer holding "packed" data
+    /// \param transid Transaction ID value
+    /// \param out_buffer Output buffer holding "packed" data
     ///
     /// \return false, if pack operation failed.
     static bool pack(const dhcp::Option::Universe universe,
@@ -74,17 +73,18 @@ public:
 
     /// \brief Handles selective binary packet parsing.
     ///
-    /// Function handles parsing of packets that have non-default
-    /// options or transaction id offsets. Client class has to use
+    /// This method handles the parsing of packets that have non-default
+    /// options or transaction ID offsets. The client class has to use
     /// \ref isc::dhcp::Pkt6::addOption to specify which options to parse.
     /// Each option should be of the \ref isc::perfdhcp::LocalizedOption
-    /// type with offset value specified.
+    /// type with the offset value specified.
     ///
     /// \param universe universe used, V4 or V6
     /// \param in_buffer input buffer to be parsed
     /// \param options options collection with options offsets
     /// \param transid_offset offset of transaction id in input buffer
     /// \param transid transaction id value read from input buffer
+    ///
     /// \return false, if unpack operation failed.
     static bool unpack(const dhcp::Option::Universe universe,
                        const dhcp::OptionBuffer& in_buffer,
@@ -95,7 +95,7 @@ public:
 private:
     /// \brief Replaces contents of options in a buffer.
     ///
-    /// The method uses localized options collection to
+    /// The method uses a localized options collection to
     /// replace parts of packet data (e.g. data read
     /// from template file).
     /// This private method is called from \ref PktTransform::pack
@@ -103,6 +103,7 @@ private:
     /// \param in_buffer input buffer holding initial packet data.
     /// \param out_buffer output buffer with "packed" options.
     /// \param options options collection with actual data and offsets.
+    ///
     /// \throw isc::Unexpected if options update failed.
     static void packOptions(const dhcp::OptionBuffer& in_buffer,
                             const dhcp::Option::OptionCollection& options,
@@ -111,22 +112,22 @@ private:
     /// \brief Reads contents of specified options from buffer.
     ///
     /// The method reads options data from the input buffer
-    /// and stores it in options objects. Offsets of options
-    /// must be specified.
-    /// (see \ref LocalizedOption to find out how to specify
-    /// option offset).
+    /// and stores it in options objects. Offsets of the options
+    /// must be specified (see \ref LocalizedOption to find out how to specify
+    /// the option offset).
     /// This private method is called by \ref PktTransform::unpack.
     ///
-    /// \note This method iterates through all options in
-    /// options collection, checks offset of the option
+    /// \note This method iterates through all options in an
+    /// options collection, checks the offset of the option
     /// in input buffer and reads data from the buffer to
-    /// update option's buffer. If provided options collection
-    /// is empty, call to this function will have no effect.
+    /// update the option's buffer. If the provided options collection
+    /// is empty, a call to this method will have no effect.
     ///
     /// \param universe universe used, V4 or V6
     /// \param in_buffer input buffer to be parsed.
     /// \param options oprions collection with their offsets
     /// in input buffer specified.
+    ///
     /// \throw isc::Unexpected if options unpack failed.
     static void unpackOptions(const dhcp::OptionBuffer& in_buffer,
                               const dhcp::Option::OptionCollection& options);

tests/tools/perfdhcp/tests/perf_pkt4_unittest.cc

@@ -35,16 +35,16 @@ typedef PerfPkt4::LocalizedOptionPtr LocalizedOptionPtr;
 
 namespace {
 
-// a dummy MAC address, padded with 0s
+// A dummy MAC address, padded with 0s
 const uint8_t dummyChaddr[16] = {0, 1, 2, 3, 4, 5, 0, 0,
                                  0, 0, 0, 0, 0, 0, 0, 0 };
 
-// let's use some creative test content here (128 chars + \0)
+// Let's use some creative test content here (128 chars + \0)
 const uint8_t dummyFile[] = "Lorem ipsum dolor sit amet, consectetur "
     "adipiscing elit. Proin mollis placerat metus, at "
     "lacinia orci ornare vitae. Mauris amet.";
 
-// yet another type of test content (64 chars + \0)
+// Yet another type of test content (64 chars + \0)
 const uint8_t dummySname[] = "Lorem ipsum dolor sit amet, consectetur "
     "adipiscing elit posuere.";
 
@@ -88,8 +88,7 @@ public:
 
         // If this is a first call to this function. Initialize
         // remaining data.
-        if (buf.size() == sizeof(hdr))
-        {
+        if (buf.size() == sizeof(hdr)) {
 
             // Append the large header fields.
             std::copy(dummyChaddr, dummyChaddr + Pkt4::MAX_CHADDR_LEN,
@@ -116,7 +115,7 @@ TEST_F(PerfPkt4Test, Constructor) {
     // Initialize some dummy payload.
     uint8_t data[250];
     for (int i = 0; i < 250; i++) {
-        data[i]=i;
+        data[i] = i;
     }
 
     // Test constructor to be used for incoming messages.
@@ -251,10 +250,10 @@ TEST_F(PerfPkt4Test, InvalidOptions) {
     // It will not match because option is shifted by on byte.
     ASSERT_FALSE(pkt1->rawUnpack());
 
-    // Crete another packet.
+    // Create another packet.
     boost::scoped_ptr<PerfPkt4> pkt2(new PerfPkt4(&buf[0], buf.size()));
 
-    // Create DHO_DHCP_MESSAGE_TYPE option that has wrong offset.
+    // Create DHO_DHCP_MESSAGE_TYPE option that has the wrong offset.
     // With this offset, option goes beyond packet size (268).
     LocalizedOptionPtr opt_msg_type(new LocalizedOption(Option::V4,
                                                         DHO_DHCP_MESSAGE_TYPE,
@@ -351,7 +350,7 @@ TEST_F(PerfPkt4Test, UnpackTransactionId) {
                                                   in_data.size(),
                                                   270));
 
-    cout << "Testing unpack of transaction id at invalid offset."
+    cout << "Testing unpack of transaction id at invalid offset. "
          << "This may produce spurious errors." << endl;
 
     // Unpack is supposed to fail because transaction id is at