added some more docs for callouts

[libasyncio] / asyncio / async_callout.cpp

diff --git a/asyncio/async_callout.cpp b/asyncio/async_callout.cpp
index 16c1347..10089e3 100644 (file)
--- a/asyncio/async_callout.cpp
+++ b/asyncio/async_callout.cpp
@@ -20,7 +20,9 @@ on this file might be covered by the GNU General Public License.
 /**
  * @file
  *
- * @copyright © Copyright 2008 by Intra2net AG
+ * @copyright © Copyright 2008-2009 by Intra2net AG
+ * @contact opensource@intra2net.com
+ *
  */
 #include "async_callout.hpp"
 #include <asyncio_config.hpp>
@@ -38,6 +40,7 @@ on this file might be covered by the GNU General Public License.
 namespace AsyncIo
 {
 
+// anonymous namespace for our secret details :-)
 namespace
 {
 
@@ -65,6 +68,10 @@ unsigned long create_call_out_id_value()
 } // eo create_call_out_id_value
 
 
+/**
+ * @brief add a caller instance to the local call map.
+ * @param caller the caller instance.
+ */
 void add_call( CallerPtr caller )
 {
    if (caller->joinId())
@@ -74,6 +81,12 @@ void add_call( CallerPtr caller )
 } // eo add_call
 
 
+/**
+ * @brief removes an entry from the local call map
+ * @param id_value id to remove from the map.
+ * @return @a true if an entry was found and removed
+ *  @a false if entry was not found in the map.
+ */
 bool remove_call( unsigned long id_value )
 {
    CallMap::iterator it= l_call_map.find(id_value);
@@ -86,6 +99,11 @@ bool remove_call( unsigned long id_value )
 } // eo remove_call(unsigned long)
 
 
+/**
+ * @brief return the caller for an id.
+ * @param id_value the id to search the caller for.
+ * @return caller; empty pointer if not found.
+ */
 CallerPtr get_call(unsigned long id_value)
 {
    CallMap::iterator it= l_call_map.find(id_value);
@@ -97,6 +115,11 @@ CallerPtr get_call(unsigned long id_value)
 } // eo get_call(unsigned long)
 
 
+/**
+ * @brief tests if an id can be found in the call map.
+ * @param id_value the id to search for.
+ * @return @a true if the id is found in the call map.
+ */
 bool has_call( unsigned long id_value )
 {
    CallMap::iterator it= l_call_map.find(id_value);
@@ -125,6 +148,16 @@ CallOutId::CallOutId(unsigned long value)
 } // eo CallOutId::CallOutId(unsigned long)
 
 
+/**
+ * @brief thaws (activate) the referenced (and frozen) call.
+ * @return @a true if the call was successfully thawed; @a false else.
+ *
+ * A call (referenced the id instance) can be successfully thawed if:
+ * - the call was a frozen call
+ * - the call is still existing; i.e. we are within the given time period
+ *   for that call.
+ * .
+ */
 bool CallOutId::thaw() const
 {
    if (m_caller_weak_ptr.expired())
@@ -140,6 +173,13 @@ bool CallOutId::thaw() const
 } // eo CallOutId::thaw() const
 
 
+/**
+ * @brief removes the referenced call.
+ * @return @a true if the call was removed; @a false else.
+ *
+ * @note after calling this method, the refernced call is not existing.
+ * Either it was removed or it was already removed earlier (explicit or implicit).
+ */
 bool CallOutId::remove()
 {
    if (m_caller_weak_ptr.expired())
@@ -152,6 +192,12 @@ bool CallOutId::remove()
 } // eo CallOutId::remove()
 
 
+/**
+ * @brief returns if the referenced call is still active.
+ * @return @a true if the referenced call is active.
+ *
+ * The referenced call is active if it is still waiting to be executed.
+ */
 bool CallOutId::active() const
 {
    return m_value!=0 and not m_caller_weak_ptr.expired() and has_call(m_value);
@@ -159,7 +205,7 @@ bool CallOutId::active() const
 
 
 /**
- * @brief retruns if the call is frozen.
+ * @brief returns if the call is frozen.
  * @return @a true iff the call is frozen.
  */
 bool CallOutId::frozen() const
@@ -178,6 +224,8 @@ bool CallOutId::frozen() const
  * @return the remaining time.
  *
  * The result only makes sense if the call is still active.
+ *
+ * If the references call is not active then the returned time is 0.
  */
 MilliTime CallOutId::remaining_time()
 {