[2435] Update isc::datasrc::RRsetCollectionBase class documentation

src/lib/datasrc/rrset_collection_base.h

@@ -29,6 +29,29 @@ class ZoneUpdater;
 ///
 /// This is a default datasrc implementation of
 /// \c isc::dns::RRsetCollectionBase that adds datasrc related detail.
+///
+/// While it is a concrete class to be used along with a \c ZoneUpdater,
+/// specific \c ZoneUpdater implementations may derive from it and add
+/// additional detail. Unless you are implementing a \c ZoneUpdater, you
+/// must not use the constructor directly. Instead use the
+/// \c ZoneUpdater::getRRsetCollection() method to get a reference to
+/// the \c RRsetCollectionBase object for that \c ZoneUpdater. This is
+/// usually a singleton object and the API is designed with this in
+/// mind, because multiple \c RRsetCollectionBase objects cannot be used
+/// at the same time in most kinds of database implementations
+/// (esp. where iterators are in use). Specific \c ZoneUpdaters that can
+/// allow multiple \c RRsetCollection objects may provide additional
+/// API, but that is unspecified here.
+///
+/// There are some restrictions on when an \c RRsetCollection may be
+/// used. Though code may have a reference to an \c RRsetCollection
+/// object, it is not always valid to use it. Implementations of
+/// \c ZoneUpdater may disable an \c RRsetCollection previously returned
+/// by \c ZoneUpdater::getRRsetCollection() after \c commit() is called
+/// on the \c ZoneUpdater. An \c isc::dns::RRsetCollectionError
+/// exception will be thrown if an \c RRsetCollection is used when
+/// disabled. Please see the \c ZoneUpdater methods' documentation for
+/// more detail.
 class RRsetCollectionBase : public isc::dns::RRsetCollectionBase {
 public:
     /// \brief Constructor.