[2850] Update isWritable() API doc

diff --git a/src/lib/datasrc/memory/zone_table_segment.h b/src/lib/datasrc/memory/zone_table_segment.h
index 8c55c1d8dd342f69ed3aa3d4fe47986b4b93993a..7b670b0ed5814d59fc6a60b5279d912fa611e6f3 100644 (file)
--- a/src/lib/datasrc/memory/zone_table_segment.h
+++ b/src/lib/datasrc/memory/zone_table_segment.h
@@ -107,9 +107,11 @@ public:
     /// \brief Return true if the segment is writable.
     ///
     /// The user of the zone table segment will load or update zones
-    /// into the segment only for writable ones.  "local" segments will
-    /// always be writable.  a "mapped" segment will be writable if a
-    /// mapped memory segment in read-write mode has been set.
+    /// into the segment only for writable ones.  The precise definition
+    /// of "writability" differs in different derived classes (see
+    /// derived class documentation).  In general, however, the user
+    /// should only rely on this interface rather than assume a specific
+    /// definition for a specific type of segment.
     virtual bool isWritable() const = 0;
 
     /// \brief Create an instance 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 41463e2097f37901c6392a54e1ef86f15e0d510c..7728c1acacdac0ce2f225e336f8e71c7b903bfa2 100644 (file)
--- a/src/lib/datasrc/memory/zone_table_segment_local.h
+++ b/src/lib/datasrc/memory/zone_table_segment_local.h
@@ -55,7 +55,8 @@ public:
 
     /// \brief Return true if the segment is writable.
     ///
-    /// This implementation always returns true.
+    /// Local segments are always writable. This implementation always
+    /// returns true.
     virtual bool isWritable() const {
         return (true);
     }

diff --git a/src/lib/datasrc/memory/zone_table_segment_mapped.h b/src/lib/datasrc/memory/zone_table_segment_mapped.h
index d30c1f08caa4cafc9e3766458c5b6ff9391fde45..2835e597b33794e16a9d555e5148826ad51ff75c 100644 (file)
--- a/src/lib/datasrc/memory/zone_table_segment_mapped.h
+++ b/src/lib/datasrc/memory/zone_table_segment_mapped.h
@@ -63,8 +63,10 @@ public:
     /// successful \c reset() call first.
     virtual isc::util::MemorySegment& getMemorySegment();
 
-    /// \brief Return true if the segment is writable. For read-only
-    /// segments, false is returned.
+    /// \brief Returns if the segment is writable.
+    ///
+    /// Segments successfully opened in CREATE or READ_WRITE modes are
+    /// writable. Segments opened in READ_ONLY mode are not writable.
     ///
     /// \throws isc::Unexpected if this method is called without a
     /// successful \c reset() call first.