[2206] Update doc comments to remove redundant bits

Also correct comments where wrong, and add a code comment for
ZoneTableSegment::create().

diff --git a/src/lib/datasrc/memory/zone_table_segment.cc b/src/lib/datasrc/memory/zone_table_segment.cc
index d818675814f46d47c4330bc7a41c96a4ce0c3ca2..94357c8a7c9d1066b0b2b35f25cbaf2a47ec4716 100644 (file)
--- a/src/lib/datasrc/memory/zone_table_segment.cc
+++ b/src/lib/datasrc/memory/zone_table_segment.cc
@@ -21,7 +21,11 @@ namespace memory {
 
 ZoneTableSegment*
 ZoneTableSegment::create(const isc::data::Element&) {
-     return (new ZoneTableSegmentLocal);
+    /// FIXME: For now, we always return ZoneTableSegmentLocal. This
+    /// should be updated eventually to parse the passed Element
+    /// argument and construct a corresponding ZoneTableSegment
+    /// implementation.
+    return (new ZoneTableSegmentLocal);
 }
 
 } // namespace memory

diff --git a/src/lib/datasrc/memory/zone_table_segment.h b/src/lib/datasrc/memory/zone_table_segment.h
index db5f74a8d1be2b24e231ae3430f02f7bb88e08df..89389a5fba3579f8cdd717c5389eb5c9110c942e 100644 (file)
--- a/src/lib/datasrc/memory/zone_table_segment.h
+++ b/src/lib/datasrc/memory/zone_table_segment.h
@@ -27,35 +27,37 @@ namespace isc {
 namespace datasrc {
 namespace memory {
 
-/// \brief Zone Table Header Class
+/// \brief Memory-management independent entry point that contains a
+/// pointer to a zone table in memory.
+///
+/// An instance of this type lives inside a ZoneTableSegment
+/// implementation. It contains an offset pointer to the zone table (a
+/// map from domain names to zone locators) in memory.
 struct ZoneTableHeader {
     boost::interprocess::offset_ptr<ZoneTable> table;
 };
 
-/// \brief Zone Table Segment Class
+/// \brief Manages a ZoneTableHeader, an entry point into a table of
+/// zones
 ///
 /// This class specifies an interface for derived implementations which
 /// return a pointer to an object of type ZoneTableHeader, an entry
-/// point of some memory image regardless of the underlying memory
-/// management implementation.
+/// point into a table of zones regardless of the underlying memory
+/// management implementation. Derived classes would implement the
+/// interface for specific memory-implementation behavior.
 class ZoneTableSegment {
 public:
     /// \brief Destructor
     virtual ~ZoneTableSegment() {}
 
-    /// \brief Return a ZoneTableHeader for the zone table segment.
-    ///
-    /// Returns a ZoneTableHeader that contains a pointer to the zone
-    /// table data in memory.
+    /// \brief Return the ZoneTableHeader for the zone table segment.
     ///
-    /// \return Returns a ZoneTableHeader for this zone table segment.
+    /// \return Returns the ZoneTableHeader for this zone table segment.
     virtual ZoneTableHeader* getHeader() = 0;
 
     /// \brief Return the MemorySegment for the zone table segment.
     ///
-    /// Returns the MemorySegment used in this zone table segment.
-    ///
-    /// \return Returns a ZoneTableHeader for this zone table segment.
+    /// \return Returns the ZoneTableHeader for this zone table segment.
     virtual isc::util::MemorySegment& getMemorySegment() = 0;
 
     /// \brief Create a subclass depending on the memory segment model

diff --git a/src/lib/datasrc/memory/zone_table_segment_local.h b/src/lib/datasrc/memory/zone_table_segment_local.h
index 2d4d757c05ba2e288b2137351ab70ac1461653b8..6d823a7d8e7995e92b02a59f22316dc32fae5931 100644 (file)
--- a/src/lib/datasrc/memory/zone_table_segment_local.h
+++ b/src/lib/datasrc/memory/zone_table_segment_local.h
@@ -22,7 +22,7 @@ namespace isc {
 namespace datasrc {
 namespace memory {
 
-/// \brief MemorySegmentLocal based Zone Table Segment class
+/// \brief Local implementation of ZoneTableSegment class
 ///
 /// This class specifies a concrete implementation for a
 /// MemorySegmentLocal based ZoneTableSegment. Please see the
@@ -32,19 +32,17 @@ public:
     /// \brief Destructor
     virtual ~ZoneTableSegmentLocal() {}
 
-    /// \brief Return a ZoneTableHeader for the zone table segment.
+    /// \brief Return the ZoneTableHeader for the local zone table
+    /// segment implementation.
     ///
-    /// Returns a ZoneTableHeader that contains a pointer to the zone
-    /// table data in memory.
-    ///
-    /// \return Returns a ZoneTableHeader for this zone table segment.
+    /// \return Returns the ZoneTableHeader for this zone table segment.
     virtual ZoneTableHeader* getHeader();
 
-    /// \brief Return the MemorySegment for the zone table segment.
-    ///
-    /// Returns the MemorySegment used in this zone table segment.
+    /// \brief Return the MemorySegment for the local zone table segment
+    /// implementation.
     ///
-    /// \return Returns a ZoneTableHeader for this zone table segment.
+    /// \return Returns the MemorySegment for this zone table segment (a
+    /// MemorySegmentLocal instance).
     virtual isc::util::MemorySegment& getMemorySegment();
 
 private: