From: Gerd v. Egidy <gerd.von.egidy@intra2net.com>
Date: Thu, 18 Sep 2008 14:06:23 +0000 (+0000)
Subject: libt2n: (gerd) some more documentation
X-Git-Tag: v0.4~5
X-Git-Url: http://developer.intra2net.com/git/?p=libt2n;a=commitdiff_plain;h=e162ddf298a2e8c3756c55995897374ef614cbcd

libt2n: (gerd) some more documentation
---

diff --git a/src/client_wrapper.hxx b/src/client_wrapper.hxx
index ebc9e25..14dabfb 100644
--- a/src/client_wrapper.hxx
+++ b/src/client_wrapper.hxx
@@ -36,6 +36,12 @@
 namespace libt2n
 {
 
+/** @brief provide access to client_connection singletons and call-handling function
+
+    This is an abstact base class for use with T2nSingletonWrapper. It provides access
+    to the singleton-client_connection and offers a handle-method which is used for
+    every call to a method on a t2n-server.
+*/
 class ConnectionWrapper
 {
     private:
@@ -57,8 +63,26 @@ class ConnectionWrapper
         virtual ~ConnectionWrapper()
             { }
 
+        /** @brief return active connection, create new one if not existing
+
+            Return a pointer to an active client_connection. Use detail-data
+            stored within the derived class to create a new connection if needed,
+            otherwise return an alredy active connection. The derived class has
+            to take care of destroying the connection when not needed anymore.
+        */
         virtual client_connection* get_connection()=0;
 
+        /** @brief this function is called on every execution of a method on a server
+
+            @param stubBase pointer to the command_client executing the call
+            @param f boost::function object containing the method to call and all parameters
+            @retval true if the call was successful and the original return-value of the called function can be used
+                    false if T2nSingletonWrapper has to create a return-value with the default-constructor
+
+            T2nSingletonWrapper will call this function on every execution of a server-side
+            method. This version will just call the function without any special treatment.
+            You can overload this function to implement different error handling strategies.
+        */
         virtual bool handle(command_client* stubBase, boost::function< void() > f)
         {
             f();
@@ -139,6 +163,13 @@ class T2nSingletonWrapperMessages
         static const char* NotInitializedMessage;
 };
 
+/** @brief wrap calls to server-side-functions with different error-handling strategies
+
+    Template class to access a process-wide singleton server-connection and to wrap all
+    calls using this connection with an error-handling strategy (e.g. to reconnect when
+    the connection broke). The source looks very complicated due to heavy use of templates,
+    look at the 3rd codegen example to see how to use it.
+*/
 template< class Client >
 class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 {
diff --git a/src/socket_wrapper.cpp b/src/socket_wrapper.cpp
index 313f6ca..cc10e0c 100644
--- a/src/socket_wrapper.cpp
+++ b/src/socket_wrapper.cpp
@@ -101,7 +101,7 @@ client_connection* ReconnectIgnoreFailureSocketWrapper::get_connection(void)
     return tmp;
 }
 
-/// try to execute the command, may
+/// try to execute the command, may ignore the command if server not available
 bool ReconnectIgnoreFailureSocketWrapper::handle(command_client* stubBase, boost::function< void() > f)
 {
     if (!connection_established())