[2207] Documentation of the base ZoneUpdater

src/lib/datasrc/memory/zone_updater.h

@@ -16,10 +16,57 @@ namespace isc {
 namespace datasrc {
 namespace memory {
 
+/// \brief Does an update to a zone.
+///
+/// This abstract base class represents the work of a reload of a zone.
+/// The work is divided into three stages -- load(), install() and cleanup().
+/// They should be called in this order for the effect to take place.
+///
+/// We divide them so the update of zone data can be done asynchronously,
+/// in a different thread. The install() operation is the only one that needs
+/// to be done in a critical section.
 class ZoneUpdater {
 public:
+    /// \brief Get the zone data into memory.
+    ///
+    /// This is the part that does the time-consuming loading into the memory.
+    /// This can be run in a separate thread, for example. It has no effect on
+    /// the data actually served, it only prepares them for future use.
+    ///
+    /// This is the first method you should call on the object. Never call it
+    /// multiple times.
+    ///
+    /// \note As this contains reading of files or other data sources, or with
+    ///     some other source of the data to load, it may throw quite anything.
+    ///     If it throws, do not call any other methods on the object and
+    ///     discard it.
+    /// \note After successful load(), you have to call cleanup() some time
+    ///     later.
+    /// \throw isc::Unexpected if called second time.
     virtual void load() = 0;
+    /// \brief Put the changes to effect.
+    ///
+    /// This replaces the old version of zone with the one previously prepared
+    /// by load(). It takes ownership of the old zone data, if any.
+    ///
+    /// You may call it only after successful load() and at most once.
+    ///
+    /// The operation is expected to be fast and is meant to be used inside
+    /// a critical section.
+    ///
+    /// This may throw in rare cases, depending on the concrete implementation.
+    /// If it throws, you still need to call cleanup().
+    ///
+    /// \throw isc::Unexpected if called without previous load() or for the
+    ///     second time.
     virtual void install() = 0;
+    /// \brief Clean up resources.
+    ///
+    /// This releases all resources held by owned zone data. That means the
+    /// one loaded by load() in case install() was not called or was not
+    /// successful, or the one replaced in install().
+    ///
+    /// Generally, this should never throw.
     virtual void cleanup() = 0;
 };