Comment changes

diff --git a/source/sockaddr.h b/source/sockaddr.h
index 6e4025d298cc46d0fc16719dcebf1cdad334514a..ff2f88a9b7be650064d4528f18ba3ff88ddd510e 100644 (file)
--- a/source/sockaddr.h
+++ b/source/sockaddr.h
@@ -25,11 +25,8 @@ public:
        virtual Family get_family() const = 0;
        virtual std::string str() const = 0;
 
-       /**
-       Fills the given struct sockaddr with information from this SockAddr.
-
-       @return  Number of bytes used
-       */
+       /** Fills a struct sockaddr with information from this SockAddr.  Returns
+       the number of bytes used. */
        virtual unsigned fill_sockaddr(sockaddr &) const = 0;
        virtual unsigned fill_sockaddr(sockaddr_storage &) const;
 };

diff --git a/source/socket.cpp b/source/socket.cpp
index 2cc3d88dbce4b2451909f5022b15008764bc7b2e..c4e98a363a89b9779517f9aab9c95a9cb1a84742 100644 (file)
--- a/source/socket.cpp
+++ b/source/socket.cpp
@@ -109,10 +109,6 @@ void Socket::bind(const SockAddr &addr)
        local_addr = addr.copy();
 }
 
-/**
-Closes the socket.  Most operations on the socket will throw an exception after
-this.
-*/
 void Socket::close()
 {
        if(handle==MSP_NET_INVALID_SOCKET_HANDLE)

diff --git a/source/socket.h b/source/socket.h
index d48f3503bac63c7463c41bed46e5e93665f678f2..a2cbae1a285ded03a645b377b3e2a85188213664 100644 (file)
--- a/source/socket.h
+++ b/source/socket.h
@@ -29,9 +29,18 @@ public:
        IO::Handle get_event_handle();
 
        bool is_connected() const { return connected; }
+       
+       /** Associates the socket with a local address.  There must be no existing
+       users of the address. */
        void bind(const SockAddr &);
+
+       /** Connects to a remote address.  Exact semantics depend on the socket
+       type. */
        virtual int connect(const SockAddr &) = 0;
+
+       /// Closes the socket.  Most operations will throw an exception after this.
        void close();
+
        void set_timeout(const Time::TimeDelta &);
        const SockAddr &get_local_address() const;
        const SockAddr &get_peer_address() const;

diff --git a/source/streamsocket.cpp b/source/streamsocket.cpp
index c5e19685f6f2cd615f6c34aa8532b045f7c691b2..e5f904ffdcbf4bd26851148b16790ad12a2ab374 100644 (file)
--- a/source/streamsocket.cpp
+++ b/source/streamsocket.cpp
@@ -9,9 +9,6 @@
 namespace Msp {
 namespace Net {
 
-/**
-Used by StreamListenSocket to construct a new socket from accept.
-*/
 StreamSocket::StreamSocket(SocketHandle h, const SockAddr &paddr):
        Socket(h, paddr),
        connecting(false)
@@ -22,20 +19,11 @@ StreamSocket::StreamSocket(SocketHandle h, const SockAddr &paddr):
        set_events(IO::P_INPUT);
 }
 
-/**
-Constructs a new StreamSocket.
-*/
 StreamSocket::StreamSocket(Family af, int proto):
        Socket(af, SOCK_STREAM, proto),
        connecting(false)
 { }
 
-/**
-Checks the status of an ongoing connection attempt.  If the connection fails
-with an error, an exception is thrown.
-
-@return  0 if the connection finished, 1 if not
-*/
 int StreamSocket::poll_connect(const Time::TimeDelta &timeout)
 {
        check_state(false);
@@ -80,14 +68,6 @@ int StreamSocket::poll_connect(const Time::TimeDelta &timeout)
        return 1;
 }
 
-/**
-Connects the socket to a remote address.  In non-blocking mode, this function
-may return before the connection is finished.  The caller must then use either
-the poll_connect function or an EventDispatcher to determine when the
-connection is finished.
-
-@return  0 if the connection finished, 1 if it is in progress
-*/
 int StreamSocket::connect(const SockAddr &addr)
 {
        check_state(false);
@@ -146,7 +126,6 @@ int StreamSocket::connect(const SockAddr &addr)
 
 void StreamSocket::on_event(IO::PollEvent ev)
 {
-       //cout<<"StreamSocket::on_event "<<ev<<'\n';
        if((ev&(IO::P_OUTPUT|IO::P_ERROR)) && connecting)
        {
                int err;

diff --git a/source/streamsocket.h b/source/streamsocket.h
index 37c5b8e09ae762975fc2c98d1747ddf6a7969bf0..dcc5dbd63c7025751c771ea141c148a197080436 100644 (file)
--- a/source/streamsocket.h
+++ b/source/streamsocket.h
@@ -13,20 +13,32 @@ private:
        bool connecting;
 
 public:
-       /**
-       Emitted when the socket finishes connecting.  The argument is a standard
-       error code, 0 indicating success.
-       */
+       /** Emitted when the socket finishes connecting.  The argument is a
+       platform-dependent error code. */
        sigc::signal<void, int> signal_connect_finished;
 
 private:
+       /// Used by StreamListenSocket to construct a new socket from accept.
        StreamSocket(SocketHandle, const SockAddr &);
 public:
        StreamSocket(Family, int = 0);
 
+       /** Connects to a remote address.  StreamSockets must be connected before
+       data can be sent and received.  Returns 0 if the connection was successfully
+       established, 1 if it's in progress.
+       
+       If the socket is non-blocking, this function may return before the
+       connection is fully established.  The caller must then use either the
+       poll_connect function or an EventDispatcher to finish the process. */
        virtual int connect(const SockAddr &);
+
        bool is_connecting() const { return connecting; }
+
+       /** Checks the status of a connection being established.  Returns 0 if the
+       connection was established successfully, 1 if it's still in progress.  If
+       the attempt finished due to an error, an exception is thrown. */
        int poll_connect(const Time::TimeDelta &);
+
 private:
        void on_event(IO::PollEvent);
 };