libt2n: (gerd) more documentation-polishing

[libt2n] / src / client_wrapper.hxx

diff --git a/src/client_wrapper.hxx b/src/client_wrapper.hxx
index 3370615..cb333db 100644 (file)
--- a/src/client_wrapper.hxx
+++ b/src/client_wrapper.hxx
@@ -169,6 +169,13 @@ class T2nSingletonWrapperMessages
     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.
+
+    @par Example
+    Calling remote methods is usually done via t2n_exec, this saves you from always
+    specifying which T2nSingletonWrapper-template to use when calling T2nSingletonWrapper::exec
+    @code
+    t2n_exec(&cmd_group_t2nexample_client::testfunc)("the answer is %d",42)
+    @endcode
 */
 template< class Client >
 class T2nSingletonWrapper : public T2nSingletonWrapperMessages
@@ -179,6 +186,7 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
         static std::auto_ptr<T2nSingletonWrapper> SingletonObject;
         static std::auto_ptr<ConnectionWrapper> WrappedConnection;
 
+        /// @cond
         // create a prep-method for each possible number of parameters
 #define _GEN_ARG(z,n,d) Arg ## n arg ##n
 #define _GEN_PREP(z,n,d) \
@@ -200,6 +208,7 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 
 #undef _GEN_PREP
 #undef _GEN_ARG
+        /// @endcond
 
         T2nSingletonWrapper(std::auto_ptr<Client> stub)
         {
@@ -241,6 +250,9 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 
     public:
 
+        /** @brief tell the wrapper which connection to use
+            @param wrappedConnection the connection to establish when needed
+        */
         static void set_connection(std::auto_ptr<ConnectionWrapper> wrappedConnection)
         {
             WrappedConnection=wrappedConnection;
@@ -249,15 +261,19 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
             if (SingletonObject.get() != NULL)
                 SingletonObject.reset();
         }
+
+        /// return a pointer to the ConnectionWrapper currently in use
         static ConnectionWrapper* get_connection_wrapper(void)
             { return WrappedConnection.get(); }
 
+        /// manually establish the connection without actually executing a call
         static void ensure_singleton_there(void)
         {
             if (SingletonObject.get() == NULL)
                 init();
         }
 
+        /// @cond
         // create an exec-method for each possible number of parameters
 #define _GEN_PLACEHOLDER(z,n,d) BOOST_PP_CAT(_,BOOST_PP_ADD(n,1))
 #define _GEN_EXEC(z,n,d) \
@@ -282,9 +298,11 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 
 #undef _GEN_EXEC
 #undef _GEN_PLACEHOLDER
+        /// @endcond
 
 };
 
+/// @cond
 // create an t2n_exec-method for each possible number of parameters
 #define _GEN_EXEC(z,n,d) \
         template< class Client, typename R  BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM_PARAMS(n,typename Arg) > \
@@ -300,6 +318,7 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 
 #undef _GEN_EXEC
 #undef _GEN_PLACEHOLDER
+/// @endcond
 
 }
 #endif