[(no branch, rebasing 1880-implement-the-tkey-rr)] [#1880] Added comments

diff --git a/src/lib/dns/rdata/generic/tkey_249.cc b/src/lib/dns/rdata/generic/tkey_249.cc
index 550d02ace4109533710974d957c6a1267bb0300a..886eb40375b4b60c17ffb16e6af4af0d32f92646 100644 (file)
--- a/src/lib/dns/rdata/generic/tkey_249.cc
+++ b/src/lib/dns/rdata/generic/tkey_249.cc
@@ -37,6 +37,15 @@ const uint16_t TKEY::GSS_API_MODE = 3;
 
 // straightforward representation of TKEY RDATA fields
 struct TKEYImpl {
+    /// \brief Constructor from RDATA field parameters.
+    ///
+    /// \param algorithm The DNS name of the algorithm e.g. gss-tsig.
+    /// \param inception The inception time (in seconds since 1970).
+    /// \param expire The expire time (in seconds since 1970).
+    /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3).
+    /// \param error The error code (extended error space shared with TSIG).
+    /// \param key The key (can be empty).
+    /// \param other_data The other data (can be and usually is empty).
     TKEYImpl(const Name& algorithm, uint32_t inception, uint32_t expire,
              uint16_t mode, uint16_t error, vector<uint8_t>& key,
              vector<uint8_t>& other_data) :
@@ -44,6 +53,17 @@ struct TKEYImpl {
       mode_(mode), error_(error), key_(key), other_data_(other_data)
     {}
 
+    /// \brief Constructor from RDATA field parameters.
+    ///
+    /// \param algorithm The DNS name of the algorithm e.g. gss-tsig.
+    /// \param inception The inception time (in seconds since 1970).
+    /// \param expire The expire time (in seconds since 1970).
+    /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3).
+    /// \param error The error code (extended error space shared with TSIG).
+    /// \param key_len The key length (0 means no key).
+    /// \param key The key (can be 0).
+    /// \param other_len The other data length (0 means no other data).
+    /// \param other_data The other data (can be and usually is 0).
     TKEYImpl(const Name& algorithm, uint32_t inception, uint32_t expire,
              uint16_t mode, uint16_t error, size_t key_len,
              const void* key, size_t other_len, const void* other_data) :
@@ -55,15 +75,30 @@ struct TKEYImpl {
                     static_cast<const uint8_t*>(other_data) + other_len)
     {}
 
+    /// \brief Common part of toWire methods.
+    /// \tparam Output \c OutputBuffer or \c AbstractMessageRenderer.
     template <typename Output>
     void toWireCommon(Output& output) const;
 
+    /// \brief The DNS name of the algorithm e.g. gss-tsig.
     const Name algorithm_;
+
+    /// \brief The inception time (in seconds since 1970).
     const uint32_t inception_;
+
+    /// \brief The expire time (in seconds since 1970).
     const uint32_t expire_;
+
+    /// \brief The mode e.g. Diffie-Hellman (2) or GSS-API (3).
     const uint16_t mode_;
+
+    /// \brief The error code (extended error space shared with TSIG).
     const uint16_t error_;
+
+    /// \brief The key (can be empty).
     const vector<uint8_t> key_;
+
+    /// \brief The other data (can be and usually is empty).
     const vector<uint8_t> other_data_;
 };
 
@@ -183,10 +218,10 @@ TKEY::constructFromLexer(MasterLexer& lexer, const Name* origin) {
 /// syntax", but it is not actually a domain name, it does not have to be
 /// fully qualified.
 ///
-/// The Mode field is an unsigned 16-bit decimal integer or a valid mnemonic
-/// as specified in RFC2930. Currently only "GSS-API" (case sensitive) is
-/// supported ("Diffie-Hellman" is not).
-
+/// The Mode field is an unsigned 16-bit decimal integer as specified
+/// in RFC2930 or a common mnemonic. Currently only "GSS-API" (case sensitive)
+/// is supported ("Diffie-Hellman" is not).
+///
 /// The Error field is an unsigned 16-bit decimal integer or a valid mnemonic
 /// as specified in RFC2845.  Currently, "NOERROR", "BADSIG", "BADKEY",
 /// "BADTIME", "BADMODE", "BADNAME", and "BADALG" are supported

diff --git a/src/lib/dns/rdata/generic/tkey_249.h b/src/lib/dns/rdata/generic/tkey_249.h
index 687c2bfa72c9cb5f8a04ab7ffb757ef48afbf183..d63012132daf587b3bda51196710dcefb6eb3006 100644 (file)
--- a/src/lib/dns/rdata/generic/tkey_249.h
+++ b/src/lib/dns/rdata/generic/tkey_249.h
@@ -43,6 +43,16 @@ public:
     ///
     /// This constructor internally involves resource allocation, and if
     /// it fails, a corresponding standard exception will be thrown.
+    ///
+    /// \param algorithm The DNS name of the algorithm e.g. gss-tsig.
+    /// \param inception The inception time (in seconds since 1970).
+    /// \param expire The expire time (in seconds since 1970).
+    /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3).
+    /// \param error The error code (extended error space shared with TSIG).
+    /// \param key_len The key length (0 means no key).
+    /// \param key The key (can be 0).
+    /// \param other_len The other data length (0 means no other data).
+    /// \param other_data The other data (can be and usually is 0).
     TKEY(const Name& algorithm, uint32_t inception, uint32_t expire,
          uint16_t mode, uint16_t error, uint16_t key_len,
          const void* key, uint16_t other_len, const void* other_data);

diff --git a/src/lib/dns/rdataclass.cc b/src/lib/dns/rdataclass.cc
index 4441884a3a7ebc849a9ceb4ce85f352c6a9d5169..3a3de4aa330e1c30ab16760a14eab4180e6ac84e 100644 (file)
--- a/src/lib/dns/rdataclass.cc
+++ b/src/lib/dns/rdataclass.cc
@@ -5185,12 +5185,33 @@ const uint16_t TKEY::GSS_API_MODE = 3;
 
 // straightforward representation of TKEY RDATA fields
 struct TKEYImpl {
+    /// \brief Constructor from RDATA field parameters.
+    ///
+    /// \param algorithm The DNS name of the algorithm e.g. gss-tsig.
+    /// \param inception The inception time (in seconds since 1970).
+    /// \param expire The expire time (in seconds since 1970).
+    /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3).
+    /// \param error The error code (extended error space shared with TSIG).
+    /// \param key The key (can be empty).
+    /// \param other_data The other data (can be and usually is empty).
     TKEYImpl(const Name& algorithm, uint32_t inception, uint32_t expire,
              uint16_t mode, uint16_t error, vector<uint8_t>& key,
              vector<uint8_t>& other_data) :
       algorithm_(algorithm), inception_(inception), expire_(expire),
       mode_(mode), error_(error), key_(key), other_data_(other_data)
     {}
+
+    /// \brief Constructor from RDATA field parameters.
+    ///
+    /// \param algorithm The DNS name of the algorithm e.g. gss-tsig.
+    /// \param inception The inception time (in seconds since 1970).
+    /// \param expire The expire time (in seconds since 1970).
+    /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3).
+    /// \param error The error code (extended error space shared with TSIG).
+    /// \param key_len The key length (0 means no key).
+    /// \param key The key (can be 0).
+    /// \param other_len The other data length (0 means no other data).
+    /// \param other_data The other data (can be and usually is 0).
     TKEYImpl(const Name& algorithm, uint32_t inception, uint32_t expire,
              uint16_t mode, uint16_t error, size_t key_len,
              const void* key, size_t other_len, const void* other_data) :
@@ -5201,15 +5222,31 @@ struct TKEYImpl {
         other_data_(static_cast<const uint8_t*>(other_data),
                     static_cast<const uint8_t*>(other_data) + other_len)
     {}
+
+    /// \brief Common part of toWire methods.
+    /// \tparam Output \c OutputBuffer or \c AbstractMessageRenderer.
     template <typename Output>
     void toWireCommon(Output& output) const;
 
+    /// \brief The DNS name of the algorithm e.g. gss-tsig.
     const Name algorithm_;
+
+    /// \brief The inception time (in seconds since 1970).
     const uint32_t inception_;
+
+    /// \brief The expire time (in seconds since 1970).
     const uint32_t expire_;
+
+    /// \brief The mode e.g. Diffie-Hellman (2) or GSS-API (3).
     const uint16_t mode_;
+
+    /// \brief The error code (extended error space shared with TSIG).
     const uint16_t error_;
+
+    /// \brief The key (can be empty).
     const vector<uint8_t> key_;
+
+    /// \brief The other data (can be and usually is empty).
     const vector<uint8_t> other_data_;
 };
 
@@ -5225,6 +5262,8 @@ TKEY::constructFromLexer(MasterLexer& lexer, const Name* origin) {
     const uint32_t expire =
         timeFromText32(lexer.getNextToken(MasterToken::STRING).getString());
 
+    /// The mode is either a mnemonic (only one is defined: GSS-API) or
+    /// a number.
     const string& mode_txt =
         lexer.getNextToken(MasterToken::STRING).getString();
     uint32_t mode = 0;
@@ -5237,7 +5276,7 @@ TKEY::constructFromLexer(MasterLexer& lexer, const Name* origin) {
             mode = boost::lexical_cast<uint32_t>(mode_txt);
         } catch (const boost::bad_lexical_cast&) {
             isc_throw(InvalidRdataText, "Invalid TKEY Mode");
-            }
+        }
         if (mode > 0xffff) {
             isc_throw(InvalidRdataText, "TKEY Mode out of range");
         }
@@ -5327,10 +5366,10 @@ TKEY::constructFromLexer(MasterLexer& lexer, const Name* origin) {
 /// syntax", but it is not actually a domain name, it does not have to be
 /// fully qualified.
 ///
-/// The Mode field is an unsigned 16-bit decimal integer or a valid mnemonic
-/// as specified in RFC2920. Currently only "GSS-API" (case sensitive) is
-/// supported ("Diffie-Hellman" is not).
-
+/// The Mode field is an unsigned 16-bit decimal integer as specified
+/// in RFC2930 or a common mnemonic. Currently only "GSS-API" (case sensitive)
+/// is supported ("Diffie-Hellman" is not).
+///
 /// The Error field is an unsigned 16-bit decimal integer or a valid mnemonic
 /// as specified in RFC2845.  Currently, "NOERROR", "BADSIG", "BADKEY",
 /// "BADTIME", "BADMODE", "BADNAME", and "BADALG" are supported
@@ -5374,7 +5413,7 @@ TKEY::TKEY(const std::string& tkey_str) : impl_(0) {
         MasterLexer lexer;
         lexer.pushSource(ss);
 
-        impl_ptr.reset(constructFromLexer(lexer, NULL));
+        impl_ptr.reset(constructFromLexer(lexer, 0));
 
         if (lexer.getNextToken().getType() != MasterToken::END_OF_FILE) {
             isc_throw(InvalidRdataText,
@@ -5431,7 +5470,7 @@ TKEY::TKEY(MasterLexer& lexer, const Name* origin,
 /// must check consistency between the length parameter and the actual
 /// RDATA length.
 TKEY::TKEY(InputBuffer& buffer, size_t) :
-    impl_(NULL)
+    impl_(0)
 {
     Name algorithm(buffer);
 
@@ -5709,7 +5748,7 @@ TKEY::getOtherData() const {
     if (!impl_->other_data_.empty()) {
         return (&impl_->other_data_[0]);
     } else {
-        return (NULL);
+        return (0);
     }
 }
 

diff --git a/src/lib/dns/rdataclass.h b/src/lib/dns/rdataclass.h
index f42a867d635299b5fabcd3580f0398b06321d699..aa7138ce09a6535c56c30593a2299e106fe4725c 100644 (file)
--- a/src/lib/dns/rdataclass.h
+++ b/src/lib/dns/rdataclass.h
@@ -2127,10 +2127,21 @@ public:
     /// The parameters are a straightforward mapping of %TKEY RDATA
     /// fields as defined %in RFC2930.
     ///
-    /// This RR is pretty close to the TSIG one with 32 bit timestamps.
+    /// This RR is pretty close to the TSIG RR with 32 bit timestamps,
+    /// or the RRSIG RR with a second "other" data field.
     ///
     /// This constructor internally involves resource allocation, and if
     /// it fails, a corresponding standard exception will be thrown.
+    ///
+    /// \param algorithm The DNS name of the algorithm e.g. gss-tsig.
+    /// \param inception The inception time (in seconds since 1970).
+    /// \param expire The expire time (in seconds since 1970).
+    /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3).
+    /// \param error The error code (extended error space shared with TSIG).
+    /// \param key_len The key length (0 means no key).
+    /// \param key The key (can be 0).
+    /// \param other_len The other data length (0 means no other data).
+    /// \param other_data The other data (can be and usually is 0).
     TKEY(const Name& algorithm, uint32_t inception, uint32_t expire,
          uint16_t mode, uint16_t error, uint16_t key_len,
          const void* key, uint16_t other_len, const void* other_data);