ChangeLogTag:Thu

4 files changed, 70 insertions, 30 deletions

diff --git a/ACE/ChangeLog b/ACE/ChangeLog
index 30950a8a6a6..e324e41832c 100644
--- a/ACE/ChangeLog
+++ b/ACE/ChangeLog
@@ -1,3 +1,11 @@
+Thu Apr 25 16:51:06 UTC 2013  Douglas C. Schmidt  <schmidt@dre.vanderbilt.edu>
+
+        * ace/Svc_Handler.h: 
+          ace/Connector.h: 
+          ace/Acceptor.h:  Added template parameter documentation.
+          Thanks to Clyde Gerber <clyde_gerber at symantec dot com> for
+          contributing this.
+
 Thu Apr 25 07:20:58 UTC 2013  Johnny Willemsen  <jwillemsen@remedy.nl>
 
         * etc/ace.doxygen:
diff --git a/ACE/ace/Acceptor.h b/ACE/ace/Acceptor.h
index e0114d4a437..8ea84f19f03 100644
--- a/ACE/ace/Acceptor.h
+++ b/ACE/ace/Acceptor.h
@@ -34,20 +34,28 @@ ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  * activating the SVC_HANDLER.
  *
  * Implements the basic strategy for passively establishing
- * connections with clients.  An ACE_Acceptor is parameterized
- * by concrete types that conform to the interfaces of
- * PEER_ACCEPTOR and SVC_HANDLER.  The PEER_ACCEPTOR is
- * instantiated with a transport mechanism that passively
- * establishes connections.  The SVC_HANDLER is instantiated
- * with a concrete type that performs the application-specific
- * service.  An ACE_Acceptor inherits from ACE_Service_Object,
- * which in turn inherits from ACE_Event_Handler.  This enables
- * the ACE_Reactor to dispatch the ACE_Acceptor's handle_input
- * method when connection events occur.  The handle_input method
- * performs the ACE_Acceptor's default creation, connection
- * establishment, and service activation strategies.  These
- * strategies can be overridden by subclasses individually or as
- * a group.
+ * connections with clients.  An ACE_Acceptor inherits from
+ * ACE_Service_Object, which in turn inherits from ACE_Event_Handler.
+ * This enables the ACE_Reactor to dispatch the ACE_Acceptor's
+ * handle_input method when connection events occur.  The handle_input
+ * method performs the ACE_Acceptor's default creation, connection
+ * establishment, and service activation strategies.  These strategies
+ * can be overridden by subclasses individually or as a group.
+ *
+ * An ACE_Acceptor is parameterized by concrete types that conform to
+ * the interfaces of SVC_HANDLER and PEER_ACCEPTOR described below.
+ *
+ * @tparam SVC_HANDLER The name of the concrete type that performs the
+ *         application-specific service.  The SVC_HANDLER typically
+ *         inherits from ACE_Svc_Handler.  @see Svc_Handler.h.
+ *
+ * @tparam PEER_ACCEPTOR The name of the class that implements the
+ *         PEER_ACCEPTOR endpoint (e.g., ACE_SOCK_Acceptor) to
+ *         passively establish connections.  A PEER_ACCEPTOR
+ *         implementation must provide a PEER_STREAM and PEER_ADDR
+ *         trait to identify the type of stream (e.g.,
+ *         ACE_SOCK_Stream) and type of address (e.g., ACE_INET_Addr)
+ *         used by the endpoint.
  */
 template <typename SVC_HANDLER, typename PEER_ACCEPTOR>
 class ACE_Acceptor : public ACE_Service_Object
diff --git a/ACE/ace/Connector.h b/ACE/ace/Connector.h
index 93da3c53330..a5e77d8c875 100644
--- a/ACE/ace/Connector.h
+++ b/ACE/ace/Connector.h
@@ -147,13 +147,23 @@ private:
  * service handlers (SVC_HANDLERs).
  *
  * Implements the strategy for actively establishing connections with
- * clients.  An ACE_Connector is parameterized by concrete types that
- * conform to the interfaces of PEER_CONNECTOR and SVC_HANDLER.  The
- * PEER_CONNECTOR is instantiated with a transport mechanism that
- * actively establishes connections.  The SVC_HANDLER is instantiated
- * with a concrete type that performs the application-specific
- * service.  Both blocking and non-blocking connects are supported.
- * Further, non-blocking connects support timeouts.
+ * clients.  Both blocking and non-blocking connects are supported.
+ * Moreover, non-blocking connects support timeouts.
+ *
+ * An ACE_Connector is parameterized by concrete types that conform to
+ * the interfaces of SVC_HANDLER and PEER_CONNECTOR described below.
+ *
+ * @tparam SVC_HANDLER The name of the concrete type that performs the
+ *         application-specific service.  The SVC_HANDLER typically
+ *         inherits from ACE_Svc_Handler.  @see Svc_Handler.h.
+ *
+ * @tparam PEER_CONNECTOR The name of the class that implements the
+ *         PEER_CONNECTOR endpoint (e.g., ACE_SOCK_Connector) to
+ *         passively establish connections.  A PEER_CONNECTOR
+ *         implementation must provide a PEER_STREAM and PEER_ADDR
+ *         trait to identify the type of stream (e.g.,
+ *         ACE_SOCK_Stream) and type of address (e.g., ACE_INET_Addr)
+ *         used by the endpoint.
  */
 template <typename SVC_HANDLER, typename PEER_CONNECTOR>
 class ACE_Connector : public ACE_Connector_Base<SVC_HANDLER>, public ACE_Service_Object
diff --git a/ACE/ace/Svc_Handler.h b/ACE/ace/Svc_Handler.h
index 5a8fbbfa9fe..79ba77ed11c 100644
--- a/ACE/ace/Svc_Handler.h
+++ b/ACE/ace/Svc_Handler.h
@@ -43,15 +43,29 @@ enum ACE_Svc_Handler_Close { NORMAL_CLOSE_OPERATION = 0x00,
  * @brief Defines the interface for a service that exchanges data with
  * its connected peer.
  *
- * This class provides a well-defined interface that the
- * Acceptor and Connector pattern factories use as their target.
- * Typically, client applications will subclass ACE_Svc_Handler
- * and do all the interesting work in the subclass.  One thing
- * that the ACE_Svc_Handler does contain is a PEER_STREAM
- * endpoint that is initialized by an ACE_Acceptor or
- * ACE_Connector when a connection is established successfully.
- * This endpoint is used to exchange data between a
- * ACE_Svc_Handler and the peer it is connected with.
+ * This class provides a well-defined interface that the ACE_Acceptor
+ * and ACE_Connector factories use as their target.  Typically, client
+ * applications will subclass ACE_Svc_Handler and do all the
+ * interesting work in the subclass.  An ACE_Svc_Handler is
+ * parameterized by concrete types that conform to the interfaces of
+ * PEER_ACCEPTOR and SYNCH_TRAITS described below.
+ *
+ * @tparam PEER_STREAM The name of the class that implements the
+ *         PEER_STREAM endpoint (e.g., ACE_SOCK_Stream) that is
+ *         contained in an ACE_Svc_Handler and initialized by an
+ *         ACE_Acceptor or ACE_Connector when a connection is
+ *         established successfully.  A PEER_STREAM implementation
+ *         must provide a PEER_ADDR trait (e.g., ACE_INET_Addr to
+ *         identify the type of address used by the endpoint.  This
+ *         endpoint is used to exchange data between a ACE_Svc_Handler
+ *         and the peer it is connected with.
+ *
+ * @tparam SYNCH_TRAITS The name of the synchronization traits class
+ *         that will be used by the ACE_Svc_Handler (e.g.,
+ *         ACE_NULL_SYNCH or ACE_MT_SYNCH). The synchronization traits
+ *         class provides typedefs for the mutex, condition, and
+ *         semaphore implementations the ACE_Svc_Handler will
+ *         use. @see Synch_Traits.h.
  */
 template <typename PEER_STREAM, typename SYNCH_TRAITS>
 class ACE_Svc_Handler : public ACE_Task<SYNCH_TRAITS>