added some doc comments

git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@209 270642c3-0616-0410-b53a-bc976706d245

diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox
index fe67997..8f8f736 100644 (file)
--- a/Socket/Mainpage.dox
+++ b/Socket/Mainpage.dox
@@ -53,13 +53,17 @@ namespace senf {
     To make your code more flexible, you should not pass around your
     socket in this form. Most of your code will be using only a small
     subset of the ProtocolClientSocketHandle or
-    ProtocolServerSocketHandle API. If instead of using the
+    ProtocolServerSocketHandle API. 
+    
+    If instead of using the
     fully specified handle type you use a more incomplete type, you
-    allow your code to be used with all socket which fulfill the
-    minimal requirements of your code.
-
-    This works, by defining a special reduced policy or handle for
-    your code:
+    allow your code to be used with all sockets which fulfill the
+    minimal requirements of your code. These types are based on the 
+    ClientSocketHandle and ServerSocketHandle templates which implement
+    the policy interface without providing the concrete protocol interface.
+    To use those templates you may define a special reduced policy or handle for
+    your code. By giving only an incomplete policy you thereby reduce the 
+    interface to that required by your module:
 
     \code
       typedef ClientSocketHandle<

diff --git a/Socket/SocketPolicy.hh b/Socket/SocketPolicy.hh
index be96da2..6ef2981 100644 (file)
--- a/Socket/SocketPolicy.hh
+++ b/Socket/SocketPolicy.hh
@@ -76,14 +76,18 @@
     <dd>configures, if and how buffering is configured for a socket</dd>
     </dl>
 
-    Every Policy value is identified by a class type. The policy
-    classes themselves built an inheritance hierarchy for each policy
-    axis. For each policy axis, the root of this tree is the class
-    named \e Policy \c Base (e.g. \p AddressingPolicyBase).
-
-    The senf::SocketPolicy defines the complete policy of a socket. It
+    In a concrete policy, each of these policy axis is assigned a value,
+    the policy value. This value is identified by a class type. For example,
+    possible values for <em>framingPolicy</em> are <tt>DatagramFramingPolicy</tt>
+    or <tt>StreamFramingPolicy</tt> which are classes derived from the axis
+    base class <tt>FramingPolicyBase</tt>. This base class doubles as
+    <tt>UnspecifiedFramingPolicy</tt> (which is just a typedef alias).
+    If a policy axis is assigned this Unspecified type, the axis is left
+    unspecified, the policy will be incomplete.
+    
+    The senf::SocketPolicy tempalte defines the complete policy of a socket. It
     combines a set of policy classes, one for each policy
-    axis. Together, they define the behavior of a socket handle. The
+    axis as described above. Together, they define the behavior of a socket handle. The
     socket handle instances do not implement any socket functionality
     themselves instead defering the implementation to the policy
     classes. The SocketHandle interface is therefore \e not
@@ -100,8 +104,13 @@
     compatible. If they are, the more derived SocketHandle can be
     converted (assigned to) the more basic SocketHandle.
 
+    \doc Example (concrete policy, incomplete policy, compatibility/assignment)
+
     \section policy_group_details The Policy Framework Classes
 
+   \doc Policy should be Axis here. Make clear, that this information is only 
+   needed when extending the library.
+    
     In the following discussion we will use the following conventions:
     \li \e Policy is one or \c AddressingPolicy, \c FramingPolicy, \c
         CommunicationPolicy, \c ReadPolicy, \c WritePolicy or \c

diff --git a/Socket/SocketProtocol.hh b/Socket/SocketProtocol.hh
index 165d668..1935b6e 100644 (file)
--- a/Socket/SocketProtocol.hh
+++ b/Socket/SocketProtocol.hh
@@ -225,6 +225,8 @@ namespace senf {
         protocols themselves, they are combined to build concrete protocols. This structure will
         remove a lot of code duplication. It is important to ensure, that the protocol facets do not
         overlap, since otherwise there will be problems resolving overlapping members.
+        
+        \doc init_client init_server
      */
     template <class SocketPolicy>
     class ConcreteSocketProtocol