libt2n: (gerd) some documentation improvement as preparation for release

diff --git a/src/command_client.cpp b/src/command_client.cpp
index 63ff539..52ca0f1 100644 (file)
--- a/src/command_client.cpp
+++ b/src/command_client.cpp
@@ -71,7 +71,6 @@ command_client::command_client(client_connection* _c, long long _command_timeout
 }
 
 /** @brief replace the connection currently in use with a new one
-
     @param _c pointer to the new connection
 
     @note the old connection must still be valid when this method is called,
@@ -99,6 +98,12 @@ void command_client::replace_connection(client_connection* _c)
     read_hello();
 }
 
+/** @brief return a complete packet
+    @param usec_timeout maximum microseconds to wait until the packet is complete
+    @retval packet data as std::string
+
+    @note throws a t2n_transfer_error if the timeout is exceeded
+*/
 std::string command_client::read_packet(const long long &usec_timeout)
 {
     string resultpacket;
@@ -113,6 +118,10 @@ std::string command_client::read_packet(const long long &usec_timeout)
     return resultpacket;
 }
 
+/** @brief read and check the hello message at the beginning of a connection
+
+    @note throws exceptions if something went wrong
+*/
 void command_client::read_hello()
 {
     string resultpacket;
@@ -133,7 +142,14 @@ void command_client::read_hello()
         throw t2n_version_mismatch("illegal hello received (incomplete): "+resultpacket);
 }
 
-bool command_client::check_hello(const string& hellostr)
+/** @brief check if a hello message is valid
+    @param hellostr std::string with the message to check
+    @retval true if the hello is good and complete
+
+    @note you can check incomplete hellos. you will get a false return value
+          but no exception. throws exceptions as soon as something is wrong.
+*/
+bool command_client::check_hello(const std::string& hellostr)
 {
     istringstream hello(hellostr);
 
@@ -208,6 +224,13 @@ bool command_client::check_hello(const string& hellostr)
     return true;
 }
 
+/** @brief send a command to the server and store the result
+    @param cmd pointer to a command-object
+    @param[out] res result container to store the result in
+
+    @note you can check incomplete hellos. you will get a false return value
+          but no exception. throws exceptions as soon as something is wrong.
+*/
 void command_client::send_command(command* cmd, result_container &res)
 {
     ostringstream ofs;

diff --git a/src/command_server.cpp b/src/command_server.cpp
index 6146981..035c334 100644 (file)
--- a/src/command_server.cpp
+++ b/src/command_server.cpp
@@ -50,6 +50,7 @@ command_server::command_server(server& _s)
     s.add_callback(new_connection,bind(&command_server::send_hello, boost::ref(*this), _1));
 }
 
+/// send a hello message to a new connection
 void command_server::send_hello(unsigned int conn_id)
 {
     server_connection* sc=s.get_connection(conn_id);

diff --git a/src/connection.cpp b/src/connection.cpp
index 30a0b19..c9283fe 100644 (file)
--- a/src/connection.cpp
+++ b/src/connection.cpp
@@ -46,6 +46,7 @@ void connection::close()
     }
 }
 
+/// get the number of bytes being available as next complete packet
 connection::packet_size_indicator connection::bytes_available()
 {
     // no size information -> no packet

diff --git a/src/server.cpp b/src/server.cpp
index 65ce62f..30bf7d3 100644 (file)
--- a/src/server.cpp
+++ b/src/server.cpp
@@ -68,6 +68,11 @@ void server_connection::reset_timeout()
     last_action_time=time(NULL);
 }
 
+/** @brief add a callback to one connection
+
+    @param event event the function will be called at
+    @param func functor (see boost::function) that will be called
+*/
 void server_connection::add_callback(callback_event_type event, const boost::function<void ()>& func)
 {
     if (event == new_connection)
@@ -94,10 +99,10 @@ server::~server()
 /** @brief add a callback
 
     @param event event the function will be called at
-    @param func functor (see boost function) that will be called
+    @param func functor (see boost::function) that will be called
 
     @note use boost::bind to bind to member functions like this:
-        s.add_callback(new_connection,bind(&my_class::func_to_call_back, boost::ref(*this), _1));
+        s.add_callback(new_connection,boost::bind(&my_class::func_to_call_back, boost::ref(*this), _1));
 */
 void server::add_callback(callback_event_type event, const boost::function<void (unsigned int)>& func)
 {
@@ -108,10 +113,16 @@ void server::add_callback(callback_event_type event, const boost::function<void
     {
         std::map<unsigned int, server_connection*>::iterator ie=connections.end();
         for(std::map<unsigned int, server_connection*>::iterator i=connections.begin(); i != ie; i++)
-            i->second->add_callback(event,bind(func, i->first));
+            i->second->add_callback(event,boost::bind(func, i->first));
     }
 }
 
+
+/** @brief an event occured, call all server-side callbacks
+
+    @param event event that occured
+    @param conn_id connection-id parameter that will be given to the callback-function
+*/
 void server::do_callbacks(callback_event_type event, unsigned int conn_id)
 {
     std::list<boost::function<void (unsigned int)> >::iterator i,ie=callbacks[event].end();
@@ -119,6 +130,7 @@ void server::do_callbacks(callback_event_type event, unsigned int conn_id)
         (*i)(conn_id);
 }
 
+/// add a new connection to the server
 int server::add_connection(server_connection* newconn)
 {
     unsigned int cid=next_id++;

diff --git a/src/socket_client.cpp b/src/socket_client.cpp
index 6b5b481..a26b004 100644 (file)
--- a/src/socket_client.cpp
+++ b/src/socket_client.cpp
@@ -101,6 +101,7 @@ socket_client_connection::socket_client_connection(const std::string& _path,
         do_callbacks(new_connection);
 }
 
+/// establish a connection via tcp
 void socket_client_connection::tcp_connect(int max_retries)
 {
     struct sockaddr_in sock_addr;
@@ -140,6 +141,7 @@ void socket_client_connection::tcp_connect(int max_retries)
     }
 }
 
+/// establish a connection via unix-socket
 void socket_client_connection::unix_connect(int max_retries)
 {
     struct sockaddr_un unix_addr;
@@ -168,6 +170,7 @@ void socket_client_connection::unix_connect(int max_retries)
     }
 }
 
+/// execute a connect on a prepared socket (tcp or unix) respecting timeouts
 void socket_client_connection::connect_with_timeout(struct sockaddr *sock_addr,unsigned int sockaddr_size)
 {
     set_socket_options(sock);

diff --git a/src/socket_wrapper.cpp b/src/socket_wrapper.cpp
index ac88144..313f6ca 100644 (file)
--- a/src/socket_wrapper.cpp
+++ b/src/socket_wrapper.cpp
@@ -25,6 +25,7 @@
 namespace libt2n
 {
 
+/// return active connection, create new tcp or unix connection if not existing
 client_connection* BasicSocketWrapper::get_connection(void)
 {
     if (c.get() == NULL)
@@ -40,6 +41,8 @@ client_connection* BasicSocketWrapper::get_connection(void)
     return c.get();
 }
 
+/// try to reconnect max_retries time if we encounter a t2n_communication_error 
+/// during execution of the command
 bool ReconnectSocketWrapper::handle(command_client* stubBase, boost::function< void() > f)
 {
     int tries=0;
@@ -82,6 +85,7 @@ bool ReconnectSocketWrapper::handle(command_client* stubBase, boost::function< v
     return false;
 }
 
+/// return active connection, return a dummy-connection if we can't establish one
 client_connection* ReconnectIgnoreFailureSocketWrapper::get_connection(void)
 {
     client_connection* tmp=BasicSocketWrapper::get_connection();
@@ -97,6 +101,7 @@ client_connection* ReconnectIgnoreFailureSocketWrapper::get_connection(void)
     return tmp;
 }
 
+/// try to execute the command, may
 bool ReconnectIgnoreFailureSocketWrapper::handle(command_client* stubBase, boost::function< void() > f)
 {
     if (!connection_established())