From 4feef9d7a2d96668660686d3812973e6f788359a Mon Sep 17 00:00:00 2001
From: Mikko Rasa <tdb@tdb.fi>
Date: Tue, 2 Aug 2011 11:36:09 +0300
Subject: [PATCH] Comment changes

---
 source/sockaddr.h       |  7 ++-----
 source/socket.cpp       |  4 ----
 source/socket.h         |  9 +++++++++
 source/streamsocket.cpp | 21 ---------------------
 source/streamsocket.h   | 20 ++++++++++++++++----
 5 files changed, 27 insertions(+), 34 deletions(-)

diff --git a/source/sockaddr.h b/source/sockaddr.h
index 6e4025d..ff2f88a 100644
--- 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 2cc3d88..c4e98a3 100644
--- 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 d48f350..a2cbae1 100644
--- 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 c5e1968..e5f904f 100644
--- 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 37c5b8e..dcc5dbd 100644
--- 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);
 };
-- 
2.43.0