BIND 10 trac2850_2, updated. 9e44958839b3f9d8fbe6cbd1f0c8f711763396fb [2850] Make more updates to ZoneTableSegment API documentation

[BIND 10 source code commits]

The branch, trac2850_2 has been updated
       via  9e44958839b3f9d8fbe6cbd1f0c8f711763396fb (commit)
      from  76e6edb548bfa6eb3df302ddd74ecff71caee3eb (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 9e44958839b3f9d8fbe6cbd1f0c8f711763396fb
Author: Mukund Sivaraman <muks at isc.org>
Date:   Fri May 10 19:28:58 2013 +0530

    [2850] Make more updates to ZoneTableSegment API documentation

-----------------------------------------------------------------------

Summary of changes:
 src/lib/datasrc/memory/zone_table_segment.h |   29 +++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

-----------------------------------------------------------------------
diff --git a/src/lib/datasrc/memory/zone_table_segment.h b/src/lib/datasrc/memory/zone_table_segment.h
index 4cfaa5a..f1d1a16 100644
--- a/src/lib/datasrc/memory/zone_table_segment.h
+++ b/src/lib/datasrc/memory/zone_table_segment.h
@@ -134,16 +134,22 @@ public:
 
     /// \brief Return the \c ZoneTableHeader for the zone table segment.
     ///
+    /// As long as \c isUsable() returns true, this method must always
+    /// succeed without throwing an exception.  If \c isUsable() returns
+    /// false, a derived class implementation can throw
+    /// \c isc::InvalidOperation depending on its implementation
+    /// details. Applications are generally expected to call this
+    /// method only when \c isUsable() returns true (either by making
+    /// sure explicitly or by some other indirect means).
+    ///
     /// \throw isc::InvalidOperation may be thrown by some
     /// implementations if this method is called without calling
     /// \c reset() successfully first.
     virtual ZoneTableHeader& getHeader() = 0;
 
-    /// \brief const version of \c getHeader().
+    /// \brief \c const version of \c getHeader().
     ///
-    /// \throw isc::InvalidOperation may be thrown by some
-    /// implementations if this method is called without calling
-    /// \c reset() successfully first.
+    /// See the non- \c const version for documentation.
     virtual const ZoneTableHeader& getHeader() const = 0;
 
     /// \brief Return the MemorySegment for the zone table segment.
@@ -249,19 +255,26 @@ public:
     /// the \c ZoneTableSegment must be usable as before.
     ///
     /// In case a \c ZoneTableSegment was reset successfully before and
-    /// is currently usable (\c isUsable() returns true), and an attempt
-    /// to to reset to a different \c MemorySegment storage area fails,
+    /// is currently usable (\c isUsable() returns true), and the attempt
+    /// to reset to a different \c MemorySegment storage area fails,
     /// the \c ResetFailed exception must be thrown. In this
     /// case, a strong exception safety guarantee must be provided, and
     /// the \c ZoneTableSegment must be usable as before.
     ///
     /// In case a \c ZoneTableSegment was reset successfully before and
-    /// is currently usable (\c isUsable() returns true), and an attempt
-    /// to to reset to the same \c MemorySegment storage area fails, the
+    /// is currently usable (\c isUsable() returns true), and the attempt
+    /// to reset to the same \c MemorySegment storage area fails, the
     /// \c ResetFailedAndSegmentCleared exception must be thrown. In
     /// this case, only basic exception safety guarantee is provided and
     /// the \c ZoneTableSegment must be expected as cleared.
     ///
+    /// In case a \c ZoneTableSegment was not reset successfully before
+    /// and is currently not usable (\c isUsable() returns false), and
+    /// the attempt to reset fails, the \c ResetFailed exception must be
+    /// thrown. In this unique case, a strong exception safety guarantee
+    /// is provided by default, as the \c ZoneTableSegment was clear
+    /// previously, and remains cleared.
+    ///
     /// In all other cases, \c ZoneTableSegment contents can be expected
     /// as reset.
     ///