From: Mukund Sivaraman <muks@isc.org>
Date: Thu, 2 May 2013 13:47:56 +0000 (+0530)
Subject: [2850] Update isWritable() API doc
X-Git-Tag: bind10-1.2.0beta1-release~467^2~72
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=26326a8f0780a2603c7ff7268998fbcce7bc5dbc;p=thirdparty%2Fkea.git

[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 8c55c1d8dd..7b670b0ed5 100644
--- 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 41463e2097..7728c1acac 100644
--- 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 d30c1f08ca..2835e597b3 100644
--- 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.