ChangeLogTag:Wed Nov 1 14:11:48 2000 Carlos O'Ryan <coryan@uci.edu>

1 files changed, 70 insertions, 78 deletions

diff --git a/ace/SOCK_Stream.h b/ace/SOCK_Stream.h
index e6263bf0f87..1917d3f6010 100644
--- a/ace/SOCK_Stream.h
+++ b/ace/SOCK_Stream.h
@@ -1,18 +1,15 @@
 /* -*- C++ -*- */
-// $Id$
-
-// ============================================================================
-//
-// = LIBRARY
-//    ace
-//
-// = FILENAME
-//    SOCK_Stream.h
-//
-// = AUTHOR
-//    Doug Schmidt
-//
-// ============================================================================
+
+//=============================================================================
+/**
+ *  @file    SOCK_Stream.h
+ *
+ *  $Id$
+ *
+ *  @author Doug Schmidt
+ */
+//=============================================================================
+
 
 #ifndef ACE_SOCK_STREAM_H
 #define ACE_SOCK_STREAM_H
@@ -26,106 +23,99 @@
 
 #include "ace/INET_Addr.h"
 
+/**
+ * @class ACE_SOCK_Stream
+ *
+ * @brief Defines the methods in the <ACE_SOCK_Stream> abstraction.
+ *
+ * This adds additional wrapper methods atop the <ACE_SOCK_IO>
+ * class.
+ *
+ * <buf> is the buffer to write from or receive into.
+ * <len> is the number of bytes to transfer.
+ * The <timeout> parameter in the following methods indicates how
+ * long to blocking trying to transfer data.  If <timeout> == 0,
+ * then the call behaves as a normal send/recv call, i.e., for
+ * blocking sockets, the call will block until action is possible;
+ * for non-blocking sockets, EWOULDBLOCK will be returned if no
+ * action is immediately possible.
+ * If <timeout> != 0, the call will wait until the relative time
+ * specified in *<timeout> elapses.
+ * The "_n()" I/O methods keep looping until all the data has been
+ * transferred.  These methods also work for sockets in non-blocking
+ * mode i.e., they keep looping on EWOULDBLOCK.  <timeout> is used
+ * to make sure we keep making progress, i.e., the same timeout
+ * value is used for every I/O operation in the loop and the timeout
+ * is not counted down.
+ * The return values for the "*_n()" methods match the return values
+ * from the non "_n()" methods and are specified as follows:
+ * - On complete transfer, the number of bytes transferred is returned.
+ * - On timeout, -1 is returned, errno == ETIME.
+ * - On error, -1 is returned, errno is set to appropriate error.
+ * - On EOF, 0 is returned, errno is irrelevant.
+ *
+ * On partial transfers, i.e., if any data is transferred before
+ * timeout/error/EOF, <bytes_transferred> will contain the number of
+ * bytes transferred.
+ * Methods with <iovec> parameter are I/O vector variants of the I/O
+ * operations.
+ * Methods with the extra <flags> argument will always result in
+ * <send> getting called. Methods without the extra <flags> argument
+ * will result in <send> getting called on Win32 platforms, and
+ * <write> getting called on non-Win32 platforms.
+ */
 class ACE_Export ACE_SOCK_Stream : public ACE_SOCK_IO
 {
-  // = TITLE
-  //     Defines the methods in the <ACE_SOCK_Stream> abstraction.
-  //
-  // = DESCRIPTION
-  //     This adds additional wrapper methods atop the <ACE_SOCK_IO>
-  //     class.
-  //
-  // = NOTES
-  // <buf> is the buffer to write from or receive into.
-  //
-  // <len> is the number of bytes to transfer.
-  //
-  // The <timeout> parameter in the following methods indicates how
-  // long to blocking trying to transfer data.  If <timeout> == 0,
-  // then the call behaves as a normal send/recv call, i.e., for
-  // blocking sockets, the call will block until action is possible;
-  // for non-blocking sockets, EWOULDBLOCK will be returned if no
-  // action is immediately possible.
-  //
-  // If <timeout> != 0, the call will wait until the relative time
-  // specified in *<timeout> elapses.
-  //
-  // The "_n()" I/O methods keep looping until all the data has been
-  // transferred.  These methods also work for sockets in non-blocking
-  // mode i.e., they keep looping on EWOULDBLOCK.  <timeout> is used
-  // to make sure we keep making progress, i.e., the same timeout
-  // value is used for every I/O operation in the loop and the timeout
-  // is not counted down.
-  //
-  // The return values for the "*_n()" methods match the return values
-  // from the non "_n()" methods and are specified as follows:
-  //
-  // - On complete transfer, the number of bytes transferred is returned.
-  // - On timeout, -1 is returned, errno == ETIME.
-  // - On error, -1 is returned, errno is set to appropriate error.
-  // - On EOF, 0 is returned, errno is irrelevant.
-  //
-  // On partial transfers, i.e., if any data is transferred before
-  // timeout/error/EOF, <bytes_transferred> will contain the number of
-  // bytes transferred.
-  //
-  // Methods with <iovec> parameter are I/O vector variants of the I/O
-  // operations.
-  //
-  // Methods with the extra <flags> argument will always result in
-  // <send> getting called. Methods without the extra <flags> argument
-  // will result in <send> getting called on Win32 platforms, and
-  // <write> getting called on non-Win32 platforms.
 public:
   // Initialization and termination methods.
+  /// Constructor.
   ACE_SOCK_Stream (void);
-  // Constructor.
 
+  /// Constructor (sets the underlying <ACE_HANDLE> with <h>).
   ACE_SOCK_Stream (ACE_HANDLE h);
-  // Constructor (sets the underlying <ACE_HANDLE> with <h>).
 
+  /// Destructor.
   ~ACE_SOCK_Stream (void);
-  // Destructor.
 
   // = I/O functions.
 
+  /// Try to recv exactly <len> bytes into <buf> from <handle>.
   ssize_t recv_n (void *buf,
                   size_t len,
                   int flags,
                   const ACE_Time_Value *timeout = 0,
                   size_t *bytes_transferred = 0) const;
-  // Try to recv exactly <len> bytes into <buf> from <handle>.
 
+  /// Try to recv exactly <len> bytes into <buf> from <handle>.
   ssize_t recv_n (void *buf,
                   size_t len,
                   const ACE_Time_Value *timeout = 0,
                   size_t *bytes_transferred = 0) const;
-  // Try to recv exactly <len> bytes into <buf> from <handle>.
 
+  /// Receive an <iovec> of size <iovcnt> to the connected socket.
   ssize_t recvv_n (iovec iov[],
                    size_t iovcnt,
                    const ACE_Time_Value *timeout = 0,
                    size_t *bytes_transferred = 0) const;
-  // Receive an <iovec> of size <iovcnt> to the connected socket.
 
+  /// Try to send exactly <len> bytes into <buf> from <handle>.
   ssize_t send_n (const void *buf,
                   size_t len,
                   int flags,
                   const ACE_Time_Value *timeout = 0,
                   size_t *bytes_transferred = 0) const;
-  // Try to send exactly <len> bytes into <buf> from <handle>.
 
+  /// Try to send exactly <len> bytes into <buf> from <handle>.
   ssize_t send_n (const void *buf,
                   size_t len,
                   const ACE_Time_Value *timeout = 0,
                   size_t *bytes_transferred = 0) const;
-  // Try to send exactly <len> bytes into <buf> from <handle>.
 
+  /// Send an <iovec> of size <iovcnt> to the connected socket.
   ssize_t sendv_n (const iovec iov[],
                    size_t iovcnt,
                    const ACE_Time_Value *timeout = 0,
                    size_t *bytes_transferred = 0) const;
-  // Send an <iovec> of size <iovcnt> to the connected socket.
 
   // = Send/receive ``urgent'' data (see TCP specs...).
   ssize_t send_urg (const void *ptr,
@@ -137,24 +127,26 @@ public:
                     const ACE_Time_Value *timeout = 0) const;
 
   // = Selectively close endpoints.
+  /// Close down the reader.
+  /// Close down the writer.
   int close_reader (void);
-  // Close down the reader.
   int close_writer (void);
-  // Close down the writer.
 
+  /**
+   * Close down the socket (we need this to make things work correctly
+   * on Win32, which requires use to do a <close_writer> before doing
+   * the close to avoid losing data).
+   */
   int close (void);
-  // Close down the socket (we need this to make things work correctly
-  // on Win32, which requires use to do a <close_writer> before doing
-  // the close to avoid losing data).
 
   // = Meta-type info
   typedef ACE_INET_Addr PEER_ADDR;
 
+  /// Dump the state of an object.
   void dump (void) const;
-  // Dump the state of an object.
 
+  /// Declare the dynamic allocation hooks.
   ACE_ALLOC_HOOK_DECLARE;
-  // Declare the dynamic allocation hooks.
 };
 
 #if !defined (ACE_LACKS_INLINE_FUNCTIONS)