X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FFileHandle.hh;h=5f82eaf103c5bb175999b8a842017dab3ef3b3a2;hb=3601c83f32cad85638739f891218f1e5d9fa0896;hp=d2c93b61c63bcfa04b94043b7c19a99cb286a397;hpb=70256cc93f59f5d2c9b3428775a181e5e225bfc5;p=senf.git

diff --git a/Socket/FileHandle.hh b/Socket/FileHandle.hh
index d2c93b6..5f82eaf 100644
--- a/Socket/FileHandle.hh
+++ b/Socket/FileHandle.hh
@@ -24,6 +24,46 @@
     \brief senf::FileHandle public header
  */
 
+/** \defgroup handle_group The Handle Hierarchy
+
+    \image html FhHierarchy.png
+
+    The senf::FileHandle class is the base of a hierarchy of socket
+    handle classes (realized as templates). These classes provide an
+    interface to the complete socket API. While going down the
+    inheritance hierarchy, the interface will be more and more
+    complete.
+
+    The most complete interface is provided by
+    senf::ProtocolClientSocketHandle and
+    senf::ProtocolServerSocketHandle. The template Arguments specifies
+    the Protocol class of the underlying socket type. These are the
+    \e only classes having public constructors and are therefore the
+    only classes, which may be created by the library user. You will
+    normally use these classes by naming a specific socket typedef
+    (e.g. senf::TCPv4ClientSocketHandle).
+    
+    However, to aid writing flexible and generic code, the socket
+    library provides the senf::ClientSocketHandle and
+    senf::ServerSocketHandle class templates. These templates
+    implement a family of closely related classes based on the
+    specification of the socket policy. This policy specification may
+    be \e incomplete (see below). Instances of
+    senf::ClientSocketHandle/senf::ServerSocketHandle can be assigned
+    and converted to different ClientSocketHandle/ServerSocketHandle
+    types as long as the policy specifications are compatible.
+
+    \attention It is very important, to (almost) always pass the socket
+    handle <em>by value</em>. The socket handle is a very lightweight
+    class and designed to be used like an ordinary built-in type. This
+    is very important in combination with the policy interface.
+
+    \note The FileHandle hierarchy below the SocketHandle template is
+    \e not meant to be user extensible. To add new socket types, you
+    should introduce new protocol and/or policy classes, the
+    SocketHandle classes should not be changed.
+ */
+
 #ifndef HH_FileHandle_
 #define HH_FileHandle_ 1
 
@@ -36,7 +76,9 @@
 #include "FileHandle.ih"
 
 namespace senf {
-
+    
+    /// \addtogroup handle_group
+    /// @{
     
     /** \brief Basic file handle wrapper
 
@@ -151,8 +193,18 @@ namespace senf {
         FileBody::ptr body_;
     };
 
+    /** \brief Adapt FileHandle to senf::Scheduler
+	\related senf::FileHandle
+
+	\internal
+
+	This function will be called by the Scheduler to retrieve the file descriptor of the
+	FileHandle.
+     */
     int retrieve_filehandle(FileHandle handle);
 
+    /// @}
+
 }
 
 ///////////////////////////////hh.e////////////////////////////////////////