Socket: Documentation for new addressing classes

Socket/Mainpage.dox

@@ -24,27 +24,79 @@ namespace senf {
 
 /** \mainpage The SENF Socket Library
 
-    The Socket library provides a high level and object oriented abstraction of the BSD socket
-    API. The abstraction is based on several concepts:
+    The Socket library provides a high level and object oriented abstraction based on the BSD socket
+    API (but not limited to it). 
+    
+    \autotoc
+    
+    \section socket_intro Introduction
 
-    \li The basic visible interface is a \link handle_group handle object \endlink
+    The socket library abstraction is based on several concepts:
+
+    \li The basic visible interface is a \link handle_group handle object\endlink
     \li The socket interface relies on a \link policy_group policy framework \endlink to configure
         it's functionality
     \li The rest of the socket API is accessible using a classic inheritance hierarchy of \link
         protocol_group protocol classes \endlink
+    \li There is a family of auxilliary \ref addr_group to supplement the socket library
+
+    \see
+        \ref structure \n
+        \ref usage
+
+
+    \section socket_handle Socket Handles
 
     The handle/body architecture provides automatic reference counted management of socket
-    instances, the policy framework provides highly efficient access to the most important socket
-    functions (like reading and writing) and the inheritance hierarchy provides convenient access to
-    the multitude of special and protocol dependent options.
+    instances. This is the visible interface to the socket library.
+
+    Each specific protocol is used primarily via a protocol specific handle (a typedef
+    symbol). However, more generic kinds of handles can be defined for more generic functionality.
 
     \see 
-        \ref structure \n
-        \ref usage \n
         \ref handle_group \n
-        \ref policy_group \n
-        \ref protocol_group \n
-        \ref addr_group \n
+        \ref concrete_protocol_group
+
+    
+    \section socket_policy The Policy interface
+
+    The policy framework configures the exact features, a specific type of socket handle
+    provides. This offers highly efficient access to the most important socket functions (like
+    reading and writing). The policy interface however is a \e static, non-polymorphic interface.
+
+    \see
+        \ref policy_group
+    
+    \section socket_protocol The Protocol interface
+
+    The protocol interface provides further protocol dependent and (possibly) polymorphic access to
+    further socket funcitonality. On the other hand, this type of interface is not as flexible,
+    generic and fast as the policy interface.
+
+    \see
+        \ref protocol_group
+    
+    \section socket_addr Auxilliary Addressing classes
+    
+    To supplement the socket library, there are a multitude of addressing classes. These come in two
+    basic groups:
+    \li Protocol specific addresses (e.g. INet4Address, MACAddress)
+    \li Socket addresses (\c sockaddr) (e.g. INet4SocketAddress, LLSocketAddress)
+
+    Whereas the protocol specific addresses are custom value types which represent their
+    corresponding low-level address, the socket addresses are based on the corresponding \c sockaddr
+    structures. 
+    
+    \see
+        \ref addr_group
+
+    \section socket_further Going further
+
+    The socket library is highly flexible and extensible. The implementation is not restricted to
+    plain BSD sockets: Any type of read/write communication can be wrapped into the socket library
+    (one Example is the TapSocketHandle which provides access to a Linux \c tap device).
+
+    \see
         \ref extend \n
         \ref implementation
  */

Socket/Protocols/BSDSocketAddress.hh

@@ -36,21 +36,49 @@
 
 namespace senf {
 
-    /** \brief
+    /** \brief Socket addressing, BSD style
+        
+        BSDSocketAddress is the base class of all BSD \c sockaddr based addressing classes. The \c
+        sockaddr addressing interface is split into several parts
+
+        \li The BSDSocketAddress provides a read-only and generic \c sockaddr interface
+        \li Address family specific derived classes implement addressing of a specific type. These
+            are INet4SocketAddress (\c AF_INET), INet6SocketAddress (\c AF_INET6), UNSocketAddress
+            (\c AF_UNIX) and LLSocketAddress (\c AF_PACKET)
+        \li GenericBSDSocketAddress provides writable support for generic addresses.
+
+        It is \e not possible to create or store BSDSocketAddress instances: You must either store
+        an address in one of the specifically typed subclasses or using GenericBSDSocketAddress.
+
+        All these classes provide a generic \c sockaddr API to interface with legacy \c sockaddr
+        based code (e.g. the BSD socket API). In this base-class, this interface is read-only, the
+        derived classes however provide a read-write interface.
+
+        \ingroup addr_group
       */
     class BSDSocketAddress
         : public senf::comparable_safe_bool<BSDSocketAddress>
     {
     public:
-        
-        bool operator==(BSDSocketAddress const & other) const;
-        bool operator!=(BSDSocketAddress const & other) const;
-
-        bool boolean_test() const;
-        short family() const;
+        bool operator==(BSDSocketAddress const & other) const; ///< Compare two arbitrary addresses
+                                        /**< For addresses to be considered equal, they must have
+                                             the same family, length and the data must be
+                                             identical. */
+        bool operator!=(BSDSocketAddress const & other) const; ///< Inverse of operator==
+
+        bool boolean_test() const;      ///< Return \c true, if address is not empty
+                                        /**< An address is considered empty if
+                                             \li the family is AF_UNSPEC
+                                             \li or the size is 0
+                                             \li or all data bytes are 0 */
+
+        short family() const;           ///< Return the address family.
+                                        /**< This value is found in the \c addressFamily member of
+                                             each typed derived class
+                                             (e.g. INet4Address::addressFamily) */
 
         ///////////////////////////////////////////////////////////////////////////
-        ///\name Generic \c sockaddr interface
+        ///\name Generic sockaddr interface
         ///\{
 
         struct sockaddr const * sockaddr_p() const;
@@ -74,15 +102,43 @@ namespace senf {
         socklen_t len_;
     };
 
+    /** \brief Safe socket address down-cast
+
+        sockaddr_cast allows to safely cast a socket address to it's derived type. Only the family
+        specific derived addressing classes are permissible for \a Target.
+
+        This cast is especially useful to cast a GenericBSDSocketAddress to it's concrete type.
+
+        \related BSDSocketAddress
+     */
     template <class Target>
     Target & sockaddr_cast(BSDSocketAddress & source);
 
+    /** \brief Safe socket address down-cast (const)
+        \see sockaddr_cast()
+        \related BSDSocketAddress
+     */
     template <class Target>
     Target const & sockaddr_cast(BSDSocketAddress const & source);
 
+    /** \brief Output generic socket address
+
+        This stream operator will output a generic BSDSocketAddress in a family depending format.
+        
+        \related BSDSocketAddress
+     */
     std::ostream & operator<<(std::ostream & os, BSDSocketAddress const & addr);
 
-    /** \brief
+    /** \brief Generic BSD \c sockaddr storage
+
+        While BSDSocketAddress provides read-only generic \c sockaddr access,
+        GenericBSDSocketAddress allows to store (write) arbitrary socket addresses. (It is
+        internally based on \c sockaddr_storage). 
+
+        To access the stored address, use sockaddr_cast to cast the GenericBSDSocketAddress to the
+        correct family specific address class.
+
+        \ingroup addr_group
       */
     class GenericBSDSocketAddress
         : public BSDSocketAddress
@@ -101,7 +157,7 @@ namespace senf {
         
         ///@}
         ///////////////////////////////////////////////////////////////////////////
-        ///\name Generic \c sockaddr interface
+        ///\name Generic sockaddr interface
         ///\{
 
         struct sockaddr const * sockaddr_p() const;

Socket/Protocols/UN/ConnectedUNDatagramSocketHandle.hh

@@ -40,9 +40,6 @@
 
 namespace senf {
 
-    /// \addtogroup concrete_protocol_group
-    /// @{
-
     typedef MakeSocketPolicy<
         UNAddressingPolicy,
         DatagramFramingPolicy,
@@ -51,6 +48,9 @@ namespace senf {
         WriteablePolicy
         >::policy ConnectedUNDatagramSocket_Policy;   ///< Socket Policy of the Unix Domain Datagram Protocol (connected)
 
+    /// \ingroup concrete_protocol_group
+    /// \{
+
     /** \brief Unix Domain Datagram Socket Protocol (connected)
 
         \par Socket Handle typedefs:
@@ -101,6 +101,8 @@ namespace senf {
 
     typedef ProtocolClientSocketHandle<ConnectedUNDatagramSocketProtocol> ConnectedUNDatagramClientSocketHandle;
 
+    ///\}
+
 }
 
 ///////////////////////////////hh.e////////////////////////////////////////