[2850] Make more updates to ZoneTableSegment API documentation

src/lib/datasrc/memory/zone_table_segment.h

@@ -288,17 +288,23 @@ public:
     ///
     /// \throw isc::InvalidParameter if the configuration in \c params
     /// has incorrect syntax, but there is a strong exception safety
-    /// guarantee and the \c ZoneTableSegment is usable as before.
+    /// guarantee and the \c ZoneTableSegment is usable or unusable as
+    /// before.
     ///
     /// \throw ResetFailed if there was a problem in opening the new
     /// memory store, but there is a strong exception safety guarantee
-    /// and the \c ZoneTableSegment is usable as before.
+    /// and the \c ZoneTableSegment is usable or unusable as before.
     ///
     /// \throw ResetFailedAndSegmentCleared if there was a problem in
     /// opening the new memory store, but there is only a basic
     /// exception safety guarantee and the \c ZoneTableSegment is not
     /// usable without a further successful \c reset().
     ///
+    /// \throw isc::NotImplemented Some implementations may choose to
+    /// not implement this method. In this case, there must be a strong
+    /// exception safety guarantee and the \c ZoneTableSegment is usable
+    /// or unusable as before.
+    ///
     /// \param mode The open mode (see the MemorySegmentOpenMode
     /// documentation).
     /// \param params An element containing implementation-specific
@@ -316,7 +322,10 @@ public:
     /// configured \c MemorySegment and clear the `ZoneTableSegment` to
     /// a freshly constructed state.
     ///
-    /// \throw none
+    /// \throw isc::NotImplemented Some implementations may choose to
+    /// not implement this method. In this case, there must be a strong
+    /// exception safety guarantee and the \c ZoneTableSegment is usable
+    /// or unusable as before.
     virtual void clear() = 0;
 
     /// \brief Return true if the \c ZoneTableSegment has been

src/lib/datasrc/memory/zone_table_segment_local.h

@@ -24,15 +24,16 @@ namespace isc {
 namespace datasrc {
 namespace memory {
 
-/// \brief Local implementation of ZoneTableSegment class
+/// \brief Local implementation of \c ZoneTableSegment class
 ///
 /// This class specifies a concrete implementation for a
-/// MemorySegmentLocal based ZoneTableSegment. Please see the
-/// ZoneTableSegment class documentation for usage.
+/// \c MemorySegmentLocal -based \c ZoneTableSegment. Please see the
+/// \c ZoneTableSegment class documentation for usage.
 class ZoneTableSegmentLocal : public ZoneTableSegment {
-    // This is so that ZoneTableSegmentLocal can be instantiated from
-    // ZoneTableSegment::create().
+    // This is so that \c ZoneTableSegmentLocal can be instantiated from
+    // \c ZoneTableSegment::create().
     friend class ZoneTableSegment;
+
 protected:
     /// \brief Protected constructor
     ///
@@ -40,6 +41,7 @@ protected:
     /// (\c ZoneTableSegment::create()), so this constructor is
     /// protected.
     ZoneTableSegmentLocal(const isc::dns::RRClass& rrclass);
+
 public:
     /// \brief Destructor
     virtual ~ZoneTableSegmentLocal();
@@ -47,18 +49,19 @@ public:
     /// \brief Returns "local" as the implementation type.
     virtual const std::string& getImplType() const;
 
-    /// \brief This method has an empty definition.
+    /// \brief This method does not have to do anything in this
+    /// implementation. It has an empty definition.
     virtual void resetHeader();
 
-    /// \brief Return the ZoneTableHeader for the local zone table
-    /// segment implementation.
+    /// \brief Return the \c ZoneTableHeader for this local zone table
+    /// segment.
     virtual ZoneTableHeader& getHeader();
 
-    /// \brief const version of \c getHeader().
+    /// \brief \c const version of \c getHeader().
     virtual const ZoneTableHeader& getHeader() const;
 
-    /// \brief Return the MemorySegment for the local zone table segment
-    /// implementation (a MemorySegmentLocal instance).
+    /// \brief Return the \c MemorySegment for the local zone table
+    /// segment implementation (a \c MemorySegmentLocal instance).
     virtual isc::util::MemorySegment& getMemorySegment();
 
     /// \brief Return true if the segment is writable.
@@ -71,12 +74,18 @@ public:
 
     /// \brief This method is not implemented.
     ///
+    /// Resetting a local \c ZoneTableSegment is not supported at this
+    /// time.
+    ///
     /// \throw isc::NotImplemented
     virtual void reset(MemorySegmentOpenMode mode,
                        isc::data::ConstElementPtr params);
 
     /// \brief This method is not implemented.
     ///
+    /// Clearing a local \c ZoneTableSegment is not supported at this
+    /// time.
+    ///
     /// \throw isc::NotImplemented
     virtual void clear();
 

src/lib/datasrc/memory/zone_table_segment_mapped.h

@@ -25,14 +25,14 @@ namespace isc {
 namespace datasrc {
 namespace memory {
 
-/// \brief Mapped-file based implementation of ZoneTableSegment class
+/// \brief Mapped-file based implementation of \c ZoneTableSegment class
 ///
 /// This class specifies a concrete implementation for a memory-mapped
-/// ZoneTableSegment. Please see the ZoneTableSegment class
+/// \c ZoneTableSegment. Please see the \c ZoneTableSegment class
 /// documentation for usage.
 class ZoneTableSegmentMapped : public ZoneTableSegment {
-    // This is so that ZoneTableSegmentMapped can be instantiated from
-    // ZoneTableSegment::create().
+    // This is so that \c ZoneTableSegmentMapped can be instantiated
+    // from \c ZoneTableSegment::create().
     friend class ZoneTableSegment;
 
 protected:
@@ -50,25 +50,25 @@ public:
     /// \brief Returns "mapped" as the implementation type.
     virtual const std::string& getImplType() const;
 
-    /// \brief Reset the table header address from the named address in
-    /// the mapped file.
+    /// \brief Resets the \c ZoneTableHeader address from the named
+    /// address in the mapped file. This method should be called once
+    /// before calls to \c getHeader() if the mapped \c MemorySegment
+    /// has grown.
     virtual void resetHeader();
 
-    /// \brief Return the ZoneTableHeader for the mapped zone table
-    /// segment implementation.
+    /// \brief Return the \c ZoneTableHeader for this mapped zone table
+    /// segment.
     ///
     /// \throws isc::InvalidOperation if this method is called without a
     /// successful \c reset() call first.
     virtual ZoneTableHeader& getHeader();
 
     /// \brief const version of \c getHeader().
-    ///
-    /// \throws isc::InvalidOperation if this method is called without a
-    /// successful \c reset() call first.
     virtual const ZoneTableHeader& getHeader() const;
 
-    /// \brief Return the MemorySegment for the memory-mapped zone table
-    /// segment implementation (a MemorySegmentMapped instance).
+    /// \brief Return the \c MemorySegment for the memory-mapped zone
+    /// table segment implementation (a \c MemorySegmentMapped
+    /// instance).
     ///
     /// \throws isc::InvalidOperation if this method is called without a
     /// successful \c reset() call first.
@@ -78,20 +78,15 @@ public:
     ///
     /// Segments successfully opened in CREATE or READ_WRITE modes are
     /// writable. Segments opened in READ_ONLY mode are not writable.
-    /// If there was a failure in \c reset(), the segment is not
-    /// writable.
+    /// If the \c ZoneTableSegment was cleared for some reason, it is
+    /// not writable until it is reset successfully.
     virtual bool isWritable() const;
 
-    /// \brief Unmap the current file (if mapped) and map the specified
-    /// one.
+    /// \brief Close the current \c MemorySegment (if open) and open the
+    /// requested one.
     ///
-    /// In case of exceptions, the current existing mapped file may be
-    /// left open, or may be cleared. Please see the \c ZoneTableSegment
-    /// API documentation for the behavior.
-    ///
-    /// See the \c MemorySegmentOpenMode documentation (in
-    /// \c ZoneTableSegment class) for the various modes in which a
-    /// \c ZoneTableSegmentMapped can be created.
+    /// See \c MemorySegmentOpenMode for a definition of "storage area"
+    /// and the various modes in which a \c MemorySegment can be opened.
     ///
     /// \c params should be a map containing a "mapped-file" key that
     /// points to a string value containing the filename of a mapped
@@ -99,11 +94,12 @@ public:
     ///
     ///  {"mapped-file": "/var/bind10/mapped-files/zone-sqlite3.mapped.0"}
     ///
-    /// \throws isc::InvalidParameter if the configuration in \c params
-    /// has incorrect syntax.
-    /// \throws isc::Unexpected for a variety of cases where an
-    /// unexpected condition occurs. These should not occur normally in
-    /// correctly written code.
+    /// Please see the \c ZoneTableSegment API documentation for the
+    /// behavior in case of exceptions.
+    ///
+    /// \throws isc::Unexpected when it's unable to lookup a named
+    /// address that it expected to be present. This is extremely
+    /// unlikely, and it points to corruption.
     ///
     /// \param mode The open mode (see the \c MemorySegmentOpenMode
     /// documentation in \c ZoneTableSegment class).
@@ -112,7 +108,9 @@ public:
     virtual void reset(MemorySegmentOpenMode mode,
                        isc::data::ConstElementPtr params);
 
-    /// \brief Unmap the current file (if mapped).
+    /// \brief Close the currently configured \c MemorySegment (if
+    /// open). See the base class for a definition of "open" and
+    /// "close".
     virtual void clear();
 
     /// \brief Return true if the segment is usable.