From 917b70786b79a9b59965d16e79ea233c93451770 Mon Sep 17 00:00:00 2001
From: tho <tho@wiback.org>
Date: Tue, 27 Feb 2007 13:55:54 +0000
Subject: [PATCH] added some doc comments
---
Socket/Mainpage.dox | 16 ++++++++++------
Socket/SocketPolicy.hh | 23 ++++++++++++++++-------
Socket/SocketProtocol.hh | 2 ++
3 files changed, 28 insertions(+), 13 deletions(-)
diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox
index fe67997ee..8f8f736b4 100644
--- 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 be96da217..6ef298149 100644
--- 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 165d66832..1935b6ee0 100644
--- 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
--
GitLab