[trac494] some documentation

src/lib/asiolink/asiolink.h

@@ -557,19 +557,39 @@ public:
                    int timeout = -1, unsigned retries = 0);
     //@}
 
+    /// \brief Initiate resolving
+    /// 
+    /// When sendQuery() is called, a (set of) message(s) is sent
+    /// asynchronously. If upstream servers are set, one is chosen
+    /// and the response (if any) from that server will be returned.
+    ///
+    /// If not upstream is set, a root server is chosen from the
+    /// root_servers, and the RunningQuery shall do a full resolve
+    /// (i.e. if the answer is a delegation, it will be followed, etc.)
+    /// until there is an answer or an error.
+    ///
+    /// When there is a response or an error and we give up, the given
+    /// CallbackPtr object shall be called (with either success() or
+    /// failure(). See ResolverInterface::Callback for more information.
+    ///
+    /// \param question The question being answered <qname/qclass/qtype>
+    /// \param callback Callback object
+    /// \param buffer An output Message into which the final response will be copied
+    /// \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
     void sendQuery(const isc::dns::QuestionPtr& question,
                    const isc::resolve::ResolverInterface::CallbackPtr callback);
 
 
-    /// \brief Initiates an upstream query in the \c RecursiveQuery object.
+    /// \brief Initiates resolving for the given question.
     ///
-    /// When sendQuery() is called, a message is sent asynchronously to
-    /// the upstream name server.  When a reply arrives, 'server'
-    /// is placed on the ASIO service queue via io_service::post(), so
-    /// that the original \c DNSServer objct can resume processing.
+    /// This actually calls the previous sendQuery() with a default
+    /// callback object, which calls resume() on the given DNSServer
+    /// object.
     ///
     /// \param question The question being answered <qname/qclass/qtype>
-    /// \param buffer An output buffer into which the response can be copied
+    /// \param buffer An output Message into which the final response will be copied
+    /// \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
     void sendQuery(const isc::dns::Question& question,
                    isc::dns::MessagePtr answer_message,

src/lib/resolve/resolver_callback.cc

@@ -18,7 +18,7 @@ namespace isc {
 namespace resolve {
 
 void
-ResolverCallbackServer::success(isc::dns::MessagePtr response)
+ResolverCallbackServer::success(const isc::dns::MessagePtr response)
 {
     // ignore our response here
     (void)response;

src/lib/resolve/resolver_callback.h

@@ -21,14 +21,21 @@
 namespace isc {
 namespace resolve {
 
+/// \short Standard Callback for sendQuery for DNSServer instances
+///
+/// This is a standard ResolverInterface::Callback implementation
+/// that is used by Resolver; when RunningQuery finishes and has either
+/// some data or an error, DNSServer::resume() will be called.
+///
+/// This class will ignore the response MessagePtr in the callback,
+/// as the server itself should also have a reference.
 class ResolverCallbackServer : public ResolverInterface::Callback {
 public:
     ResolverCallbackServer(asiolink::DNSServer* server) :
         server_(server->clone()) {}
     ~ResolverCallbackServer() { delete server_; };
     
-    //void callback(bool result);
-    void success(isc::dns::MessagePtr response);
+    void success(const isc::dns::MessagePtr response);
     void failure();
 
 private:

src/lib/resolve/resolver_interface.h

@@ -41,22 +41,36 @@ namespace resolve {
  */
 class ResolverInterface {
     public:
-        /// \short An abstract callback when data from resolver are ready.
+        /// \short An abstract callback for when the resolver is done.
+        ///
+        /// You can pass an instance of a subclass of this (as a
+        /// CallbackPtr) to RecursiveQuery::sendQuery(), and when it
+        /// is done, it will either call success() if there is an
+        /// answer MessagePtr, or failure(), if the resolver was not
+        /// able to find anything.
+        ///
+        /// Note that a result Message does not necessarily contain
+        /// the actual answer (it could be a noerror/nodata response).
         class Callback {
             public:
                 /// \short Some data arrived.
-                virtual void success(isc::dns::MessagePtr response) = 0;
+                virtual void success(const isc::dns::MessagePtr response) = 0;
                 
                 /**
                  * \short No data available.
                  *
-                 * \todo Pass some reason.
+                 * \todo Provide error reason (result of the
+                 *       classification call, for instance? We'd also
+                 *       need some way to say 'everything times out')
                  */
                 virtual void failure() = 0;
+
                 /// \short Virtual destructor, so descendants are cleaned up
-                virtual ~ Callback() {};
+                virtual ~Callback() {};
         };
+
         typedef boost::shared_ptr<Callback> CallbackPtr;
+
         /**
          * \short Ask a question.
          *
@@ -68,6 +82,7 @@ class ResolverInterface {
          */
         virtual void resolve(const isc::dns::QuestionPtr& question,
             const CallbackPtr& callback) = 0;
+
         /// \short Virtual destructor, so descendants are properly cleaned up
         virtual ~ ResolverInterface() {}
 };