From: Michal 'vorner' Vaner <michal.vaner@nic.cz>
Date: Sat, 2 Jun 2012 11:14:10 +0000 (+0200)
Subject: [1975] Description of expected usage
X-Git-Tag: trac2351_base~97^2~9^2~4^2~24
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=57e92cc0aff7f42885c0e100116ec85e9eb21dc7;p=thirdparty%2Fkea.git

[1975] Description of expected usage
---

diff --git a/src/lib/datasrc/container.h b/src/lib/datasrc/container.h
index 7d30f5c245..57d3ceb46b 100644
--- a/src/lib/datasrc/container.h
+++ b/src/lib/datasrc/container.h
@@ -98,6 +98,28 @@ public:
     /// This searches the contained data sources for a one that best matches
     /// the zone name.
     ///
+    /// There are two expected usage scenarios. One is answering queries. In
+    /// this case, the zone finder is needed and the best matching superzone
+    /// of the searched name is needed. Therefore, the call would look like:
+    ///
+    ///   SearchResult result(container->search(queried_name));
+    ///   if (result.datasrc_) {
+    ///       createTheAnswer(result.finder_);
+    ///   } else {
+    ///       createNotAuthAnswer();
+    ///   }
+    ///
+    /// The other scenario is manipulating zone data (XfrOut, XfrIn, DDNS,
+    /// ...). In this case, the finder itself is not so important. However,
+    /// we need an exact match (if we want to manipulate zone data, we must
+    /// know exactly, which zone we are about to manipulate). Then the call
+    ///
+    ///   SearchResult result(container->search(zone_name, true, false));
+    ///   if (result.datasrc_) {
+    ///       ZoneUpdaterPtr updater(result.datasrc_->getUpdater(zone_name);
+    ///       ...
+    ///   }
+    ///
     /// \param zone The name of the zone to search.
     /// \param want_exact_match If it is true, it returns only exact matches.
     ///     If the best possible match is partial, a negative result is