BIND 10 rrl, updated. 31fa468dd7124cdab67266263c8b1b39e418a189 [rrl] Add API doc for RRLKey class

[BIND 10 source code commits]

The branch, rrl has been updated
       via  31fa468dd7124cdab67266263c8b1b39e418a189 (commit)
      from  a04bf48f9cbafc3dd1c0790060e99bd0bdb3f4fe (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 31fa468dd7124cdab67266263c8b1b39e418a189
Author: Mukund Sivaraman <muks at isc.org>
Date:   Mon Dec 16 14:58:48 2013 +0530

    [rrl] Add API doc for RRLKey class

-----------------------------------------------------------------------

Summary of changes:
 src/bin/auth/rrl/rrl_key.cc |    1 -
 src/bin/auth/rrl/rrl_key.h  |   47 ++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 44 insertions(+), 4 deletions(-)

-----------------------------------------------------------------------
diff --git a/src/bin/auth/rrl/rrl_key.cc b/src/bin/auth/rrl/rrl_key.cc
index cdff98f..984efe4 100644
--- a/src/bin/auth/rrl/rrl_key.cc
+++ b/src/bin/auth/rrl/rrl_key.cc
@@ -73,7 +73,6 @@ RRLKey::RRLKey(const IOEndpoint& client_addr, const dns::RRType& qtype,
     }
 }
 
-
 } // namespace detail
 } // namespace rrl
 } // namespace auth
diff --git a/src/bin/auth/rrl/rrl_key.h b/src/bin/auth/rrl/rrl_key.h
index 78dd865..ef0f1b3 100644
--- a/src/bin/auth/rrl/rrl_key.h
+++ b/src/bin/auth/rrl/rrl_key.h
@@ -36,33 +36,74 @@ namespace auth {
 namespace rrl {
 namespace detail {
 
+/// \brief Lookup key into the RRL table.
+///
+/// This class computes a lookup key into an RRL table for a DNS
+/// response using the client's IP address, the QNAME, QTYPE, QCLASS and
+/// type of response (success, NXDOMAIN or some error). The client's IP
+/// address is used after masking off suffix bits so that only initial
+/// IPV4-PREFIX-LENGTH or IPV6-PREFIX-LENGTH bits are used for lookup
+/// key computation. IPV6-PREFIX-LENGTH allows a maximum value of 64
+/// (which should approximate most IPv6 victim target networks).
+///
+/// Implementation note: For comparisons, assignment, etc. this class
+/// does direct object-size \c memcpy(), memcmp(), etc.
 class RRLKey {
 public:
-    // For requirements of STL containers.  We don't directly use keys
-    // constructed by this.
+    /// \brief For requirements of STL containers.  We don't directly
+    /// use keys constructed by this.
     RRLKey() {}
 
+    /// \brief Constructor
+    ///
+    /// Note: Because other methods of this class do memory operations
+    /// on this object's allocation directly, all of the object's
+    /// allocation must be initialized by this constructor.
+    ///
+    /// \param client_address The address of the client. This is masked
+    /// using the \c ipv4_mask or \c ipv6_masks fields before key
+    /// computation. Note that only a maximum of 64 bits are allowed
+    /// in the client address prefix (see the class description).
+    /// \param qtype \c RRType corresponding to the QTYPE field.
+    /// \param qname \c LabelSequence corresponding to the QNAME field.
+    /// \param qclass \c RRClass corresponding to the QCLASS field.
+    /// \param resp_type Type of response that was generated for the query.
+    /// \param ipv4_mask IPv4 address mask for \c client_address.
+    /// \param ipv6_masks IPv6 address mask for \c client_address.
+    /// \param hash_seed A seed used in key computation.
     RRLKey(const asiolink::IOEndpoint& client_addr, const dns::RRType& qtype,
            const dns::LabelSequence* qname, const dns::RRClass& qclass,
            ResponseType resp_type, uint32_t ipv4_mask,
            const uint32_t ipv6_masks[4], uint32_t hash_seed);
 
+    /// \brief Assignment operator.
+    ///
+    /// Note: This does a \c memcpy() of the entire object's allocation
+    /// region. For this reason, the constructor must not leave any of
+    /// the memory uninitialized.
     RRLKey& operator=(const RRLKey& source) {
-        // See the constructor's note about ugly memcpy
         std::memcpy(this, &source, sizeof(*this));
         return (*this);
     }
 
+    /// \brief Equals operator.
+    ///
+    /// Note: This does a \c memcmp() of the entire object's allocation
+    /// region. For this reason, the constructor must not leave any of
+    /// the memory uninitialized.
     bool operator==(const RRLKey& other) const {
         return (std::memcmp(this, &other, sizeof(*this)) == 0);
     }
 
+    /// \brief Returns the hash value for this \c RRLKey.
     size_t getHash() const {
         const uint8_t* cp = static_cast<const uint8_t*>(
             static_cast<const void*>(this));
         return (boost::hash_range(cp, cp + sizeof(*this)));
     }
 
+    /// \brief Returns the response type (success, NXDOMAIN or some
+    /// error)
     ResponseType getResponseType() const { return (rtype_); }
 
 private: