[2850] Update isWritable() API doc

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

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);
     }

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.