BIND 10 trac2349, updated. 9c2e94bb8ae9368aac3e0991dbebe3738ee914d7 [2349] Documentation for the pimpling of two classes

[BIND 10 source code commits]

The branch, trac2349 has been updated
       via  9c2e94bb8ae9368aac3e0991dbebe3738ee914d7 (commit)
      from  95a47e7f0ac9e87d3d0c6c51c07e4761d0a50932 (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 9c2e94bb8ae9368aac3e0991dbebe3738ee914d7
Author: Jelte Jansen <jelte at isc.org>
Date:   Mon Oct 15 15:49:39 2012 +0200

    [2349] Documentation for the pimpling of two classes

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

Summary of changes:
 src/lib/resolve/recursive_query.cc |    9 +++++++--
 src/lib/resolve/recursive_query.h  |   39 ++++++++++++++++++++++++++++++++++--
 2 files changed, 44 insertions(+), 4 deletions(-)

-----------------------------------------------------------------------
diff --git a/src/lib/resolve/recursive_query.cc b/src/lib/resolve/recursive_query.cc
index 0c9ff85..68b06b0 100644
--- a/src/lib/resolve/recursive_query.cc
+++ b/src/lib/resolve/recursive_query.cc
@@ -1225,7 +1225,9 @@ ForwardQuery::ForwardQuery(IOService& io,
         OutputBufferPtr buffer,
         isc::resolve::ResolverInterface::CallbackPtr cb,
         int query_timeout, int client_timeout, int lookup_timeout) {
-    fqi_ = new ForwardQueryImpl(io, query_message, answer_message, upstream, buffer, cb, query_timeout, client_timeout, lookup_timeout);
+    fqi_ = new ForwardQueryImpl(io, query_message, answer_message,
+                                upstream, buffer, cb, query_timeout,
+                                client_timeout, lookup_timeout);
 }
 
 ForwardQuery::~ForwardQuery() {
@@ -1244,7 +1246,10 @@ RunningQuery::RunningQuery(isc::asiolink::IOService& io,
         isc::cache::ResolverCache& cache,
         boost::shared_ptr<RttRecorder>& recorder)
 {
-    rqi_ = new RunningQueryImpl(io, question, answer_message, test_server, buffer, cb, query_timeout, client_timeout, lookup_timeout, retries, nsas, cache, recorder);
+    rqi_ = new RunningQueryImpl(io, question, answer_message, test_server,
+                                buffer, cb, query_timeout, client_timeout,
+                                lookup_timeout, retries, nsas, cache,
+                                recorder);
 }
 
 RunningQuery::~RunningQuery() {
diff --git a/src/lib/resolve/recursive_query.h b/src/lib/resolve/recursive_query.h
index 50f0df2..a8eab8d 100644
--- a/src/lib/resolve/recursive_query.h
+++ b/src/lib/resolve/recursive_query.h
@@ -54,11 +54,23 @@ private:
 
 typedef std::vector<std::pair<std::string, uint16_t> > AddressVector;
 
+/// \brief A forwarded query
+///
+/// This class represents an active forwarded query object;
+/// i.e. an outstanding query to a different server when operating
+/// in forwarder mode.
+///
+/// It can not be instantiated directly, but is created by
+/// RecursiveQuery::forward().
+///
+/// Its only public method is its destructor, and that should in theory
+/// not be called either except in some unit tests. Instances should
+/// delete themselves when the query is finished.
 class ForwardQuery {
+    friend class RecursiveQuery;
 private:
     class ForwardQueryImpl;
     ForwardQueryImpl* fqi_;
-public:
     ForwardQuery(isc::asiolink::IOService& io,
                  isc::dns::ConstMessagePtr query_message,
                  isc::dns::MessagePtr answer_message,
@@ -66,14 +78,26 @@ public:
                  isc::util::OutputBufferPtr buffer,
                  isc::resolve::ResolverInterface::CallbackPtr cb,
                  int query_timeout, int client_timeout, int lookup_timeout);
+public:
     ~ForwardQuery();
 };
 
+/// \brief A Running query
+///
+/// This class represents an active running query object;
+/// i.e. an outstanding query to an authoritative name server.
+///
+/// It can not be instantiated directly, but is created by
+/// RecursiveQuery::resolve().
+///
+/// Its only public method is its destructor, and that should in theory
+/// not be called either except in some unit tests. Instances should
+/// delete themselves when the query is finished.
 class RunningQuery {
+    friend class RecursiveQuery;
 private:
     class RunningQueryImpl;
     RunningQueryImpl* rqi_;
-public:
     RunningQuery(isc::asiolink::IOService& io,
         const isc::dns::Question question,
         isc::dns::MessagePtr answer_message,
@@ -85,6 +109,7 @@ public:
         isc::nsas::NameserverAddressStore& nsas,
         isc::cache::ResolverCache& cache,
         boost::shared_ptr<RttRecorder>& recorder);
+public:
     ~RunningQuery();
 };
 
@@ -177,6 +202,12 @@ public:
     /// \param buffer An output buffer into which the intermediate responses will
     ///        be copied.
     /// \param server A pointer to the \c DNSServer object handling the client
+    /// \return A pointer to the active RunningQuery object created by this
+    ///         call (if any); this object should delete itself in normal
+    ///         circumstances, and can normally be ignored by the caller,
+    ///         but a pointer is returned for use-cases such as unit tests.
+    ///         Returns NULL if the data was found internally and no actual
+    ///         query was sent.
     RunningQuery* resolve(const isc::dns::Question& question,
                           isc::dns::MessagePtr answer_message,
                           isc::util::OutputBufferPtr buffer,
@@ -193,6 +224,10 @@ public:
     /// \param server Server object that handles receipt and processing of the
     ///               received messages.
     /// \param callback callback object
+    /// \return A pointer to the active ForwardQuery created by this call;
+    ///         this object should delete itself in normal circumstances,
+    ///         and can normally be ignored by the caller, but a pointer
+    ///         is returned for use-cases such as unit tests.
     ForwardQuery* forward(isc::dns::ConstMessagePtr query_message,
                  isc::dns::MessagePtr answer_message,
                  isc::util::OutputBufferPtr buffer,