From: Lucas Bajolet <r4pass@hotmail.com>
Date: Mon, 7 Apr 2014 15:32:52 +0000 (-0400)
Subject: lib/socket: Added more documentation on Socket class, also fixed a visibility issue... 
X-Git-Tag: v0.6.6~125^2~1
X-Git-Url: http://nitlanguage.org

lib/socket: Added more documentation on Socket class, also fixed a visibility issue on a constructor

Signed-off-by: Lucas Bajolet <r4pass@hotmail.com>
---

diff --git a/lib/socket/socket.nit b/lib/socket/socket.nit
index 52094cc..8919dbc 100644
--- a/lib/socket/socket.nit
+++ b/lib/socket/socket.nit
@@ -19,11 +19,23 @@ module socket
 
 import socket_c
 
+# Portal for communication between two machines
 class Socket
+	# IPv4 address the socket is connected to
+	# Formatted as xxx.xxx.xxx.xxx
 	var address: String
+
+	# Hostname of the socket connected to self
+	# In C : The real canonical host name (e.g. example.org)
 	var host: nullable String
+
+	# Port open for the socket
 	var port: Int
+
+	# Underlying C socket
 	private var socket: FFSocket
+
+	# Underlying C socket
 	private var addrin: FFSocketAddrIn
 
 	# Guard for errors
@@ -32,6 +44,7 @@ class Socket
 	# this flag will be set to false.
 	var still_alive = true # Note : HUGE SUCCESS
 
+	# Creates a socket connection to host `thost` on port `port`
 	init stream_with_host(thost: String, tport: Int)
 	do
 		socket = new FFSocket.socket( new FFSocketAddressFamilies.af_inet, new FFSocketTypes.sock_stream, new FFSocketProtocolFamilies.pf_null )
@@ -47,6 +60,7 @@ class Socket
 		port = addrin.port
 	end
 
+	# Creates a server socket on port `tport`
 	init stream_with_port(tport: Int)
 	do
 		socket = new FFSocket.socket( new FFSocketAddressFamilies.af_inet, new FFSocketTypes.sock_stream, new FFSocketProtocolFamilies.pf_null )
@@ -61,7 +75,8 @@ class Socket
 		host = null
 	end
 
-	init primitive_init(h: FFSocketAcceptResult)
+	# Creates a client socket, this is meant to be used by accept only
+	private init primitive_init(h: FFSocketAcceptResult)
 	do
 		socket = h.socket
 		addrin = h.addrIn
@@ -107,21 +122,35 @@ class Socket
 		return poll_in(events, 0).length == 0
 	end
 
+	# Establishes a connection to socket addrin
+	#
+	# REQUIRES : self.still_alive
 	fun connect: Bool do
 		assert still_alive
 		return socket.connect(addrin) >= 0
 	end
 
+	# Write a message to connected socket
+	#
+	# Returns `true` if the `msg` was sent, `false` otherwise
+	#
+	# If not socket.sill_alive, false will be returned
 	fun write(msg: String): Bool do
 		if not still_alive then return false
 		return socket.write(msg) >= 0
 	end
 
+	# Read from connected socket
+	#
+	# If the socket is disconnected, an empty string will be returned
 	fun read: String do
 		if not still_alive then return ""
 		return socket.read
 	end
 
+	# Close connection
+	#
+	# Returns : `true` if the close was successful, `false` otherwise
 	fun close: Bool do
 		if not still_alive then return true
 		if socket.close >= 0 then
@@ -131,16 +160,28 @@ class Socket
 		return false
 	end
 
+	# Associates the socket to a local address and port
+	#
+	# Returns : `true` if the socket could be bound, `false` otherwise
 	fun bind: Bool do
 		if not still_alive then return false
 		return socket.bind(addrin) >= 0
 	end
 
+	# Sets the socket as ready to accept incoming connections, `size` is the maximum number of queued clients
+	#
+	# Returns : `true` if the socket could be set, `false` otherwise
 	fun listen(size: Int): Bool do
 		if not still_alive then return false
 		return socket.listen(size) >= 0
 	end
 
+	# Accepts an incoming connection from a client
+	# This creates a new socket that represents the connection to a client
+	#
+	# Returns : the socket for communication with the client
+	#
+	# REQUIRES : self.still_alive
 	fun accept: Socket do
 		assert still_alive
 		return new Socket.primitive_init(socket.accept)