[1138] style fixes and docs in dhcid_49.h and dhcid_49.cc

diff --git a/src/lib/dns/rdata/in_1/dhcid_49.cc b/src/lib/dns/rdata/in_1/dhcid_49.cc
index 937b068bdea483fa25564d3912b2fddcd11c416b..3a34d50572d380120980f9e6d4bc7b9585659a52 100644 (file)
--- a/src/lib/dns/rdata/in_1/dhcid_49.cc
+++ b/src/lib/dns/rdata/in_1/dhcid_49.cc
@@ -31,6 +31,21 @@ using namespace isc::util;
 // BEGIN_ISC_NAMESPACE
 // BEGIN_RDATA_NAMESPACE
 
+/// \brief Constructor from string.
+///
+/// \param dhcid_str A base-64 representation of the DHCID binary data.
+/// The data is considered to be opaque, but a sanity check is performed.
+///
+/// <b>Exceptions</b>
+///
+/// \c dhcid_str must be a valid  BASE-64 string, otherwise an exception
+/// of class \c isc::BadValue will be thrown;
+/// the binary data should consist of at leat of 3 octets as per RFC4701:
+///           < 2 octets >    Identifier type code
+///           < 1 octet >     Digest type code
+///           < n octets >    Digest (length depends on digest type)
+/// If the data is less than 3 octets (i.e. it cannot contain id type code and
+/// digest type code), an exception of class \c InvalidRdataLength is thrown.
 DHCID::DHCID(const string& dhcid_str) {
     istringstream iss(dhcid_str);
     stringbuf digestbuf;
@@ -48,6 +63,13 @@ DHCID::DHCID(const string& dhcid_str) {
     }
 }
 
+/// \brief Constructor from wire-format data.
+///
+/// \param buffer A buffer storing the wire format data.
+/// \param rdata_len The length of the RDATA in bytes
+///
+/// <b>Exceptions</b>
+/// \c InvalidRdataLength is thrown if \c rdata_len is than minimum of 3 octets
 DHCID::DHCID(InputBuffer& buffer, size_t rdata_len) {
     if (rdata_len < 3) {
         isc_throw(InvalidRdataLength, "DHCID length " << rdata_len <<
@@ -58,24 +80,43 @@ DHCID::DHCID(InputBuffer& buffer, size_t rdata_len) {
     buffer.readData(&digest_[0], rdata_len);
 }
 
+/// \brief The copy constructor.
+///
+/// This trivial copy constructor never throws an exception.
 DHCID::DHCID(const DHCID& other) : Rdata(), digest_(other.digest_)
 {}
 
+/// \brief Render the \c DHCID in the wire format.
+///
+/// \param buffer An output buffer to store the wire data.
 void
 DHCID::toWire(OutputBuffer& buffer) const {
     buffer.writeData(&digest_[0], digest_.size());
 }
 
+/// \brief Render the \c DHCID in the wire format into a
+/// \c MessageRenderer object.
+///
+/// \param renderer DNS message rendering context that encapsulates the
+/// output buffer in which the \c DHCID is to be stored.
 void
 DHCID::toWire(AbstractMessageRenderer& renderer) const {
     renderer.writeData(&digest_[0], digest_.size());
 }
 
+/// \brief Convert the \c DHCID to a string.
+///
+/// This method returns a \c std::string object representing the \c DHCID.
+///
+/// \return A string representation of \c DHCID.
 string
 DHCID::toText() const {
     return (encodeHex(digest_));
 }
 
+/// \brief Compare two instances of \c DHCID RDATA.
+///
+/// See documentation in \c Rdata.
 int
 DHCID::compare(const Rdata& other) const {
     const DHCID& other_dhcid = dynamic_cast<const DHCID&>(other);
@@ -91,6 +132,9 @@ DHCID::compare(const Rdata& other) const {
     }
 }
 
+/// \brief Accessor method to get the DHCID digest
+///
+/// \return A reference to the binary DHCID data
 const std::vector<uint8_t>&
 DHCID::getDigest() const {
     return (digest_);

diff --git a/src/lib/dns/rdata/in_1/dhcid_49.h b/src/lib/dns/rdata/in_1/dhcid_49.h
index 666f2837ed49db1b17dd6086249b8fe1355aa7af..919395fba1fc0cb65c76d8436a83792266fc224d 100644 (file)
--- a/src/lib/dns/rdata/in_1/dhcid_49.h
+++ b/src/lib/dns/rdata/in_1/dhcid_49.h
@@ -26,19 +26,28 @@
 
 // BEGIN_RDATA_NAMESPACE
 
+/// \brief \c rdata::DHCID class represents the DHCID RDATA as defined %in
+/// RFC4701.
+///
+/// This class implements the basic interfaces inherited from the abstract
+/// \c rdata::Rdata class, and provides trivial accessors specific to the
+/// DHCID RDATA.
 class DHCID : public Rdata {
 public:
     // BEGIN_COMMON_MEMBERS
     // END_COMMON_MEMBERS
 
-    // subject to change
-    // DHCID& operator=(const DHCID& source);
-    // ~DHCID();
-
+    /// \brief Return the digest.
+    ///
+    /// This method never throws an exception.
     const std::vector<uint8_t>& getDigest() const;
 
 private:
-    std::vector<uint8_t> digest_;       // opaque data at least 3 octets long
+    /// \brief Private data representation
+    ///
+    /// Opaque data at least 3 octets long as per RFC4701.
+    ///
+    std::vector<uint8_t> digest_;
 };
 // END_RDATA_NAMESPACE
 // END_ISC_NAMESPACE