[2435] Make documentation updates

1 files changed, 29 insertions, 23 deletions

diff --git a/src/lib/dns/rrset_collection_base.h b/src/lib/dns/rrset_collection_base.h
index 64f6379970..4756f68273 100644
--- a/src/lib/dns/rrset_collection_base.h
+++ b/src/lib/dns/rrset_collection_base.h
@@ -58,31 +58,37 @@ public:
     /// is found, \c NULL is returned.
     ///
     /// This method's implementations currently are not specified to
-    /// handle \c RRTypes such as RRSIG and NSEC3. It's not clear
-    /// whether we want to return all RRSIGs of the given name covering
-    /// any RR types (in which case, we need to figure out how), or we
-    /// need to extend the interface so we can specify the covered
-    /// type. The libdns++ implementation (\c isc::dns::RRsetCollection)
-    /// could actually match RRSIG RRsets because its \c addRRset()
-    /// method does not reject the direct addition of RRSIGs. There are
-    /// such fundamental open questions, and a specific derived
-    /// implementation may return something if type RRSIG is specified,
-    /// but this is not specified here at the base class level, i.e.,
-    /// for RRSIGs the behavior is undefined. This interface may be
-    /// refined to clarify this point in the future, and perhaps,
-    /// provide additional API for this RRType.
+    /// handle \c RRTypes such as RRSIG and NSEC3.  This interface may be
+    /// refined to clarify this point in the future, and perhaps, provide
+    /// additional API for these RRType.
     ///
-    /// Behavior with non-concrete types such as ANY and AXFR are also
+    /// As for RRSIG, there are such fundamental open questions.  For
+    /// example, it's not clear whether we want to return all RRSIGs
+    /// of the given name covering any RR types (in which case, we
+    /// need to figure out how), or we need to extend the interface so
+    /// we can specify the covered.  A specific derived implementation
+    /// may return something if type RRSIG is specified, but this is
+    /// not specified here at the base class level, i.e., for RRSIGs
+    /// the behavior is undefined.
+    ///
+    /// As for NSEC3, it's not clear whether owner names (which included
+    /// hashed labels) are the best choice of search key, because in many
+    /// cases what the application wants to find is an NSEC3 that has the
+    /// hash of some particular "normal" domain names.  Also, if the underlying
+    /// implementation encapsulates a single zone, NSEC3 records conceptually
+    /// belong to a separate name space, which may cause implementation
+    /// difficulty.
+    ///
+    /// Behavior with meta types such as ANY and AXFR are also
     /// undefined. A specific implementation may return something for
-    /// these (a \c RRType::AXFR() RRset can be created and passed to
-    /// \c isc::dns::RRsetCollection, for example). But, unlike the case
-    /// of RRSIGs, these types of RRsets are not expected to be added to
-    /// any implementation of collection in the first place (by the
-    /// definition of "meta types"), so querying for such types is
-    /// basically an invalid operation. The API doesn't require
-    /// implementations to check this condition and reject it, so the
-    /// behavior is undefined. This interface will not be refined in
-    /// future versions for these meta types.
+    /// these.  But, unlike the case of RRSIGs, these types of RRsets
+    /// are not expected to be added to any implementation of
+    /// collection in the first place (by the definition of "meta
+    /// types"), so querying for such types is basically an invalid
+    /// operation. The API doesn't require implementations to check
+    /// this condition and reject it, so the behavior is
+    /// undefined. This interface will not be refined in future
+    /// versions for these meta types.
     ///
     /// \throw RRsetCollectionError if find() results in some
     /// implementation-specific error.