documentation update

Doxyfile.in

@@ -565,7 +565,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = @CMAKE_HOME_DIRECTORY@/cppa/ @CMAKE_HOME_DIRECTORY@/cppa/util @CMAKE_HOME_DIRECTORY@/cppa/intrusive
+INPUT                  = @CMAKE_HOME_DIRECTORY@/cppa/ @CMAKE_HOME_DIRECTORY@/cppa/util @CMAKE_HOME_DIRECTORY@/cppa/intrusive @CMAKE_HOME_DIRECTORY@/cppa/network
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 

cppa/cppa.hpp

@@ -137,6 +137,9 @@
  * @namespace cppa::intrusive
  * @brief Contains intrusive container implementations.
  *
+ * @namespace cppa::network
+ * @brief Contains all network related classes.
+ *
  * @namespace cppa::factory
  * @brief Contains factory functions to create actors from lambdas or
  *        other functors.

cppa/enable_weak_ptr_mixin.hpp

@@ -44,20 +44,20 @@
 
 namespace cppa {
 
+/**
+ * @brief Enables derived classes to be used in {@link weak_intrusive_ptr}.
+ */
 template<class Base>
 class enable_weak_ptr_mixin : public Base {
 
     typedef Base super;
 
+    template<typename T>
+    friend class weak_intrusive_ptr;
+
     static_assert(std::is_base_of<ref_counted,Base>::value,
                   "Base needs to be derived from ref_counted");
 
- public:
-
-    inline intrusive_ptr<weak_ptr_anchor> get_weak_ptr_anchor() const {
-        return m_anchor;
-    }
-
  protected:
 
     template<typename... Args>
@@ -71,6 +71,10 @@ class enable_weak_ptr_mixin : public Base {
 
  private:
 
+    inline intrusive_ptr<weak_ptr_anchor> get_weak_ptr_anchor() const {
+        return m_anchor;
+    }
+
     intrusive_ptr<weak_ptr_anchor> m_anchor;
 
 };

cppa/network/addressed_message.hpp

@@ -41,6 +41,10 @@
 
 namespace cppa { namespace network {
 
+/**
+ * @brief Encapsulates a message along with sender and receiver information
+ *        as well as its synchronous message id.
+ */
 class addressed_message {
 
  public:
@@ -99,8 +103,14 @@ class addressed_message {
 
 };
 
+/**
+ * @relates addressed_message
+ */
 bool operator==(const addressed_message& lhs, const addressed_message& rhs);
 
+/**
+ * @relates addressed_message
+ */
 inline bool operator!=(const addressed_message& lhs,
                        const addressed_message& rhs) {
     return !(lhs == rhs);

cppa/network/continuable_reader.hpp

@@ -42,6 +42,10 @@ namespace cppa { namespace network {
 
 class middleman;
 
+/**
+ * @brief Denotes the return value of
+ *        {@link continuable_reader::continue_reading()}.
+ */
 enum continue_reading_result {
     read_failure,
     read_closed,
@@ -50,6 +54,9 @@ enum continue_reading_result {
 
 class continuable_writer;
 
+/**
+ * @brief An object performing asynchronous input on a file handle.
+ */
 class continuable_reader : virtual public ref_counted {
 
  public:
@@ -65,7 +72,8 @@ class continuable_reader : virtual public ref_counted {
     virtual continue_reading_result continue_reading() = 0;
 
     /**
-     * @return Casts @p this to a continuable_writer or returns @p nullptr.
+     * @return Casts @p this to a continuable_writer, returns @p nullptr
+     *         if cast fails.
      */
     virtual continuable_writer* as_writer();
 

cppa/network/continuable_writer.hpp

@@ -37,13 +37,20 @@
 
 namespace cppa { namespace network {
 
+/**
+ * @brief Denotes the return value of
+ *        {@link continuable_writer::continue_writing()}.
+ */
 enum continue_writing_result {
     write_failure,
     write_closed,
     write_continue_later,
     write_done
 };
 
+/**
+ * @brief An object performing asynchronous output on a file handle.
+ */
 class continuable_writer : virtual public ref_counted {
 
     typedef ref_counted super;

cppa/network/middleman.hpp

@@ -45,6 +45,9 @@ namespace cppa { namespace detail { class singleton_manager; } }
 
 namespace cppa { namespace network {
 
+/**
+ * @brief Multiplexes asynchronous IO.
+ */
 class middleman {
 
     friend class detail::singleton_manager;
@@ -53,11 +56,19 @@ class middleman {
 
     virtual ~middleman();
 
+    /**
+     * @brief Add a new communication protocol to the middleman.
+     */
     virtual void add_protocol(const protocol_ptr& impl) = 0;
 
+    /**
+     * @brief Returns the protocol associated with @p id.
+     */
     virtual protocol_ptr protocol(atom_value id) = 0;
 
-    // runs @p fun in the middleman's event loop
+    /**
+     * @brief Runs @p fun in the middleman's event loop.
+     */
     virtual void run_later(std::function<void()> fun) = 0;
 
  protected:

cppa/network/middleman_event_handler_base.hpp

@@ -45,16 +45,19 @@ namespace cppa { namespace network {
 
 typedef int event_bitmask;
 
-namespace event {
+namespace event { namespace {
 
-static constexpr event_bitmask none  = 0x00;
-static constexpr event_bitmask read  = 0x01;
-static constexpr event_bitmask write = 0x02;
-static constexpr event_bitmask both  = 0x03;
-static constexpr event_bitmask error = 0x04;
+constexpr event_bitmask none  = 0x00;
+constexpr event_bitmask read  = 0x01;
+constexpr event_bitmask write = 0x02;
+constexpr event_bitmask both  = 0x03;
+constexpr event_bitmask error = 0x04;
 
-} // namespace event
+} } // namespace event
 
+/**
+ * @brief Converts an event bitmask to a human-readable string.
+ */
 inline const char* eb2str(event_bitmask e) {
     switch (e) {
         default: return "INVALID";

cppa/network/protocol.hpp

@@ -50,6 +50,9 @@ class abstract_middleman;
 class continuable_reader;
 class continuable_writer;
 
+/**
+ * @brief Implements a communication protocol.
+ */
 class protocol : public ref_counted {
 
     typedef ref_counted super;

cppa/weak_intrusive_ptr.hpp

@@ -40,6 +40,9 @@
 
 namespace cppa {
 
+/**
+ * @brief A smart pointer that does not increase the reference count.
+ */
 template<typename T>
 class weak_intrusive_ptr : util::comparable<weak_intrusive_ptr<T>> {
 
@@ -55,7 +58,7 @@ class weak_intrusive_ptr : util::comparable<weak_intrusive_ptr<T>> {
 
     /**
      * @brief Promotes this weak pointer to an intrusive_ptr.
-     * @warning Returns @p nullptr if expired.
+     * @warning Returns @p nullptr if {@link expired()}.
      */
     intrusive_ptr<T> promote() {
         return (m_anchor) ? m_anchor->get<T>() : nullptr;
@@ -74,7 +77,7 @@ class weak_intrusive_ptr : util::comparable<weak_intrusive_ptr<T>> {
 
     /**
      * @brief Queries whether this weak pointer is invalid, i.e., does not
-     *        point to an instance.
+     *        point to an object.
      */
     inline bool invalid() const {
         return m_anchor == nullptr;

cppa/weak_ptr_anchor.hpp

@@ -39,12 +39,19 @@
 
 namespace cppa {
 
+/**
+ * @brief A storage holding a spinlock and a pointer to a
+ *        reference counted object.
+ */
 class weak_ptr_anchor : public ref_counted {
 
  public:
 
     weak_ptr_anchor(ref_counted* ptr);
 
+    /**
+     * @brief Gets a pointer to the object or nullptr if {@link expired()}.
+     */
     template<typename T>
     intrusive_ptr<T> get() {
         intrusive_ptr<T> result;
@@ -55,11 +62,18 @@ class weak_ptr_anchor : public ref_counted {
         return result;
     }
 
+    /**
+     * @brief Queries whether the object was already deleted.
+     */
     inline bool expired() const {
         // no need for locking since pointer comparison is atomic
         return m_ptr == nullptr;
     }
 
+    /**
+     * @brief Tries to expire this anchor. Fails if reference count of object
+     *        is not zero.
+     */
     bool try_expire();
 
  private: