[2440] update documentation of RdataSet::create().

src/lib/datasrc/memory/rdataset.cc

@@ -50,18 +50,18 @@ getCoveredType(const Rdata& rdata) {
     }
 }
 
-// A helper for smallestTTL: restore RRTTL object from wire-format 32-bit data.
+// A helper for lowestTTL: restore RRTTL object from wire-format 32-bit data.
 RRTTL
 restoreTTL(const void* ttl_data) {
     isc::util::InputBuffer b(ttl_data, sizeof(uint32_t));
     return (RRTTL(b));
 }
 
-// A helper function for create(): return the TTL that has smallest value
+// A helper function for create(): return the TTL that has lowest value
 // amount the given those of given rdataset (if non NULL), rrset, sig_rrset.
 RRTTL
-smallestTTL(const RdataSet* rdataset, ConstRRsetPtr& rrset,
-            ConstRRsetPtr& sig_rrset)
+lowestTTL(const RdataSet* rdataset, ConstRRsetPtr& rrset,
+          ConstRRsetPtr& sig_rrset)
 {
     if (rrset && sig_rrset) {
         const RRTTL tmp(std::min(rrset->getTTL(), sig_rrset->getTTL()));
@@ -103,7 +103,7 @@ RdataSet::create(util::MemorySegment& mem_sgmt, RdataEncoder& encoder,
     if (old_rdataset && old_rdataset->type != rrtype) {
         isc_throw(BadValue, "RR type doesn't match for merging RdataSet");
     }
-    const RRTTL rrttl = smallestTTL(old_rdataset, rrset, sig_rrset);
+    const RRTTL rrttl = lowestTTL(old_rdataset, rrset, sig_rrset);
     if (old_rdataset) {
         encoder.start(rrclass, rrtype, old_rdataset->getDataBuf(),
                       old_rdataset->getRdataCount(),

src/lib/datasrc/memory/rdataset.h

@@ -120,6 +120,27 @@ public:
     /// RRSIG from the given memory segment, constructs the object, and
     /// returns a pointer to it.
     ///
+    /// If the optional \c old_rdataset parameter is set to non NULL,
+    /// The given \c RdataSet, RRset, RRSIG will be merged in the new
+    /// \c Rdataset object: the new object contain the union set of all
+    /// RDATA and RRSIGs contained in these.  Obviously \c old_rdataset
+    /// was previously generated for the same RRClass and RRType as those
+    /// for the given RRsets; it's the caller's responsibility to ensure
+    /// this condition.  If it's not met the result will be undefined.
+    ///
+    /// In both cases, this method ensures the stored RDATA and RRSIG are
+    /// unique.  Any duplicate data (in the sense of the comparison in the
+    /// form of canonical form of RRs as described in RFC4034) within RRset or
+    /// RRSIG, or between data in \c old_rdataset and RRset/RRSIG will be
+    /// unified.
+    ///
+    /// In general, the TTLs of the given data are expected to be the same.
+    /// This is especially the case if the zone is signed (and RRSIG is given).
+    /// However, if different TTLs are found among the given data, this
+    /// method chooses the lowest one for the TTL of the resulting
+    /// \c RdataSet.  This is an implementation choice, but should be most
+    /// compliant to the sense of Section 5.2 of RFC2181.
+    ///
     /// Normally the (non RRSIG) RRset is given (\c rrset is not NULL) while
     /// its RRSIG (\c sig_rrset) may or may not be provided.  But it's also
     /// expected that in some rare (mostly broken) cases there can be an RRSIG
@@ -148,9 +169,9 @@ public:
     /// happens.
     ///
     /// Due to implementation limitations, this class cannot contain more than
-    /// 8191 RDATAs for the non RRISG RRset; also, it cannot contain more than
-    /// 65535 RRSIGs.  If the given RRset(s) fail to meet this condition,
-    /// an \c RdataSetError exception will be thrown.
+    /// 8191 RDATAs (after unifying duplicates) for the non RRISG RRset; also,
+    /// it cannot contain more than 65535 RRSIGs.  If the given RRset(s) fail
+    /// to meet this condition, an \c RdataSetError exception will be thrown.
     ///
     /// \throw isc::BadValue Given RRset(s) are invalid (see the description)
     /// \throw RdataSetError Number of RDATAs exceed the limits

src/lib/datasrc/tests/memory/rdataset_unittest.cc

@@ -563,7 +563,7 @@ TEST_F(RdataSetTest, badMergeCreate) {
 }
 
 TEST_F(RdataSetTest, varyingTTL) {
-    // Creating RdataSets with different TTLs.  The smallest one should win.
+    // Creating RdataSets with different TTLs.  The lowest one should win.
 
     ConstRRsetPtr aaaa_smaller = textToRRset("example. 5 IN AAAA 2001:db8::");
     ConstRRsetPtr aaaa_small = textToRRset("example. 10 IN AAAA 2001:db8::1");