Added extra documentation for InspSocket (at last)

git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@2356 e03df62e-2008-0410-955e-edbf42e46eb7

5 files changed, 343 insertions, 156 deletions

diff --git a/docs/man/man3/InspSocket.3 b/docs/man/man3/InspSocket.3
index 9e08b1d3c..63f2475d6 100644
--- a/docs/man/man3/InspSocket.3
+++ b/docs/man/man3/InspSocket.3
@@ -2,7 +2,9 @@
 .ad l
 .nh
 .SH NAME
-InspSocket \- 
+InspSocket \- InspSocket is an extendable socket class which modules can use for TCP socket support.  
+
+.PP
 .SH SYNOPSIS
 .br
 .PP
@@ -14,60 +16,83 @@ InspSocket \-
 .ti -1c
 .RI "\fBInspSocket\fP ()"
 .br
+.RI "\fIThe default constructor does nothing and should not be used. \fP"
 .ti -1c
 .RI "\fBInspSocket\fP (int newfd, char *ip)"
 .br
+.RI "\fIThis constructor is used to associate an existing connecting with an InspSocket class. \fP"
 .ti -1c
 .RI "\fBInspSocket\fP (\fBstd::string\fP \fBhost\fP, int \fBport\fP, bool listening, unsigned long maxtime)"
 .br
+.RI "\fIThis constructor is used to create a new socket, either listening for connections, or an outbound connection to another host. \fP"
 .ti -1c
 .RI "virtual bool \fBOnConnected\fP ()"
 .br
+.RI "\fIThis method is called when an outbound connection on your socket is completed. \fP"
 .ti -1c
 .RI "virtual void \fBOnError\fP (\fBInspSocketError\fP e)"
 .br
+.RI "\fIThis method is called when an error occurs. \fP"
 .ti -1c
 .RI "virtual int \fBOnDisconnect\fP ()"
 .br
+.RI "\fIWhen an established connection is terminated, the OnDisconnect method is triggered. \fP"
 .ti -1c
 .RI "virtual bool \fBOnDataReady\fP ()"
 .br
+.RI "\fIWhen there is data waiting to be read on a socket, the \fBOnDataReady()\fP method is called. \fP"
 .ti -1c
 .RI "virtual void \fBOnTimeout\fP ()"
 .br
+.RI "\fIWhen an outbound connection fails, and the attempt times out, you will receive this event. \fP"
 .ti -1c
 .RI "virtual void \fBOnClose\fP ()"
 .br
+.RI "\fIWhenever close() is called, \fBOnClose()\fP will be called first. \fP"
 .ti -1c
 .RI "virtual char * \fBRead\fP ()"
 .br
+.RI "\fIReads all pending bytes from the socket into a char* array which can be up to 16 kilobytes in length. \fP"
 .ti -1c
 .RI "\fBstd::string\fP \fBGetIP\fP ()"
 .br
+.RI "\fIReturns the IP address associated with this connection, or an empty string if no IP address exists. \fP"
+.ti -1c
+.RI "bool \fBTimeout\fP (time_t current)"
+.br
+.RI "\fIThis function checks if the socket has timed out yet, given the current time in the parameter. \fP"
 .ti -1c
 .RI "virtual int \fBWrite\fP (\fBstd::string\fP data)"
 .br
+.RI "\fIWrites a \fBstd::string\fP to the socket. \fP"
 .ti -1c
 .RI "virtual int \fBOnIncomingConnection\fP (int newfd, char *ip)"
 .br
+.RI "\fIIf your socket is a listening socket, when a new connection comes in on the socket this method will be called. \fP"
 .ti -1c
 .RI "void \fBSetState\fP (\fBInspSocketState\fP s)"
 .br
+.RI "\fIChanges the socket's state. \fP"
 .ti -1c
 .RI "\fBInspSocketState\fP \fBGetState\fP ()"
 .br
+.RI "\fIReturns the current socket state. \fP"
 .ti -1c
 .RI "bool \fBPoll\fP ()"
 .br
+.RI "\fIOnly the core should call this function. \fP"
 .ti -1c
 .RI "int \fBGetFd\fP ()"
 .br
+.RI "\fIThis method returns the socket's file descriptor as assigned by the operating system, or -1 if no descriptor has been assigned. \fP"
 .ti -1c
 .RI "virtual void \fBClose\fP ()"
 .br
+.RI "\fIThis method causes the socket to close, and may also be triggered by other methods such as OnTimeout and OnError. \fP"
 .ti -1c
 .RI "virtual \fB~InspSocket\fP ()"
 .br
+.RI "\fIThe destructor may implicitly call \fBOnClose()\fP, and will close() and shutdown() the file descriptor used for this socket. \fP"
 .in -1c
 .SS "Private Attributes"
 
@@ -75,53 +100,69 @@ InspSocket \-
 .ti -1c
 .RI "int \fBfd\fP"
 .br
+.RI "\fIThe file descriptor of this socket. \fP"
 .ti -1c
 .RI "\fBstd::string\fP \fBhost\fP"
 .br
+.RI "\fIThe hostname connected to. \fP"
 .ti -1c
 .RI "int \fBport\fP"
 .br
+.RI "\fIThe port connected to, or the port this socket is listening on. \fP"
 .ti -1c
 .RI "\fBInspSocketState\fP \fBstate\fP"
 .br
+.RI "\fIThe state for this socket, either listening, connecting, connected or error. \fP"
 .ti -1c
 .RI "sockaddr_in \fBaddr\fP"
 .br
+.RI "\fIThe host being connected to, in sockaddr form. \fP"
 .ti -1c
 .RI "in_addr \fBaddy\fP"
 .br
+.RI "\fIThe host being connected to, in in_addr form. \fP"
 .ti -1c
 .RI "time_t \fBtimeout_end\fP"
 .br
+.RI "\fIWhen this time is reached, the socket times out if it is in the CONNECTING state. \fP"
 .ti -1c
 .RI "bool \fBtimeout\fP"
 .br
-.ti -1c
-.RI "pollfd \fBpolls\fP"
-.br
+.RI "\fIThis value is true if the socket has timed out. \fP"
 .ti -1c
 .RI "char \fBibuf\fP [16384]"
 .br
+.RI "\fISocket input buffer, used by read(). \fP"
 .ti -1c
 .RI "\fBstd::string\fP \fBIP\fP"
 .br
+.RI "\fIThe IP address being connected to stored in string form for easy retrieval by accessors. \fP"
 .ti -1c
 .RI "sockaddr_in \fBclient\fP"
 .br
+.RI "\fIClient sockaddr structure used by accept(). \fP"
 .ti -1c
 .RI "sockaddr_in \fBserver\fP"
 .br
+.RI "\fI\fBServer\fP sockaddr structure used by accept(). \fP"
 .ti -1c
 .RI "socklen_t \fBlength\fP"
 .br
+.RI "\fIUsed by accept() to indicate the sizes of the sockaddr_in structures. \fP"
 .in -1c
 .SH "Detailed Description"
 .PP 
-Definition at line 30 of file socket.h.
+InspSocket is an extendable socket class which modules can use for TCP socket support. 
+
+It is fully integrated into InspIRCds socket loop and attaches its sockets to the core's instance of the \fBSocketEngine\fP class, meaning that any sockets you create have the same power and abilities as a socket created by the core itself. To use InspSocket, you must inherit a class from it, and use the InspSocket constructors to establish connections and bindings.
+.PP
+Definition at line 47 of file socket.h.
 .SH "Constructor & Destructor Documentation"
 .PP 
 .SS "InspSocket::InspSocket ()"
 .PP
+The default constructor does nothing and should not be used. 
+.PP
 Definition at line 49 of file socket.cpp.
 .PP
 References I_DISCONNECTED, and state.
@@ -134,6 +175,10 @@ References I_DISCONNECTED, and state.
 .PP
 .SS "InspSocket::InspSocket (int newfd, char * ip)"
 .PP
+This constructor is used to associate an existing connecting with an InspSocket class. 
+.PP
+The given file descriptor must be valid, and when initialized, the InspSocket will be set with the given IP address and placed in CONNECTED state.
+.PP
 Definition at line 54 of file socket.cpp.
 .PP
 References SocketEngine::AddFd(), fd, I_CONNECTED, IP, state, and X_ESTAB_MODULE.
@@ -149,6 +194,21 @@ References SocketEngine::AddFd(), fd, I_CONNECTED, IP, state, and X_ESTAB_MODULE
 .PP
 .SS "InspSocket::InspSocket (\fBstd::string\fP host, int port, bool listening, unsigned long maxtime)"
 .PP
+This constructor is used to create a new socket, either listening for connections, or an outbound connection to another host. 
+.PP
+\fBParameters:\fP
+.RS 4
+\fIhost\fP The hostname to connect to, or bind to 
+.br
+\fIport\fP The port number to connect to, or bind to 
+.br
+\fIlistening\fP true to listen on the given host:port pair, or false to connect to them 
+.br
+\fImaxtime\fP Number of seconds to wait, if connecting, before the connection times out and an \fBOnTimeout()\fP event is generated
+.RE
+.PP
+
+.PP
 Definition at line 62 of file socket.cpp.
 .PP
 References SocketEngine::AddFd(), addr, addy, Close(), DEBUG, fd, I_CONNECTING, I_ERR_BIND, I_ERR_CONNECT, I_ERR_SOCKET, I_ERROR, I_LISTENING, IP, OnError(), state, timeout, timeout_end, and X_ESTAB_MODULE.
@@ -233,20 +293,24 @@ References SocketEngine::AddFd(), addr, addy, Close(), DEBUG, fd, I_CONNECTING,
 .PP
 .SS "InspSocket::~InspSocket ()\fC [virtual]\fP"
 .PP
-Definition at line 265 of file socket.cpp.
+The destructor may implicitly call \fBOnClose()\fP, and will close() and shutdown() the file descriptor used for this socket. 
+.PP
+Definition at line 269 of file socket.cpp.
 .PP
 References Close().
 .PP
 .nf
-266 {
-267         this->Close();
-268 }
+270 {
+271         this->Close();
+272 }
 .fi
 .PP
 .SH "Member Function Documentation"
 .PP 
 .SS "void InspSocket::Close ()\fC [virtual]\fP"
 .PP
+This method causes the socket to close, and may also be triggered by other methods such as OnTimeout and OnError. 
+.PP
 Definition at line 139 of file socket.cpp.
 .PP
 References fd, and OnClose().
@@ -267,18 +331,22 @@ Referenced by InspSocket(), and ~InspSocket().
 .PP
 .SS "int InspSocket::GetFd ()"
 .PP
-Definition at line 252 of file socket.cpp.
+This method returns the socket's file descriptor as assigned by the operating system, or -1 if no descriptor has been assigned. 
+.PP
+Definition at line 256 of file socket.cpp.
 .PP
 References fd.
 .PP
 .nf
-253 {
-254         return this->fd;
-255 }
+257 {
+258         return this->fd;
+259 }
 .fi
 .PP
 .SS "\fBstd::string\fP InspSocket::GetIP ()"
 .PP
+Returns the IP address associated with this connection, or an empty string if no IP address exists. 
+.PP
 Definition at line 150 of file socket.cpp.
 .PP
 References IP.
@@ -291,137 +359,181 @@ References IP.
 .PP
 .SS "\fBInspSocketState\fP InspSocket::GetState ()"
 .PP
-Definition at line 247 of file socket.cpp.
+Returns the current socket state. 
+.PP
+Definition at line 251 of file socket.cpp.
 .PP
 References state.
 .PP
 .nf
-248 {
-249         return this->state;
-250 }
+252 {
+253         return this->state;
+254 }
 .fi
 .PP
 .SS "void InspSocket::OnClose ()\fC [virtual]\fP"
 .PP
-Definition at line 263 of file socket.cpp.
+Whenever close() is called, \fBOnClose()\fP will be called first. 
+.PP
+Please note that this means OnClose will be called alongside \fBOnError()\fP, \fBOnTimeout()\fP, and \fBClose()\fP, and also when cancelling a listening socket by calling the destructor indirectly.
+.PP
+Definition at line 267 of file socket.cpp.
 .PP
 Referenced by Close().
 .PP
 .nf
-263 { return; }
+267 { return; }
 .fi
 .PP
 .SS "bool InspSocket::OnConnected ()\fC [virtual]\fP"
 .PP
-Definition at line 257 of file socket.cpp.
+This method is called when an outbound connection on your socket is completed. 
+.PP
+\fBReturns:\fP
+.RS 4
+false to abort the connection, true to continue
+.RE
+.PP
+
+.PP
+Definition at line 261 of file socket.cpp.
 .PP
 Referenced by Poll().
 .PP
 .nf
-257 { return true; }
+261 { return true; }
 .fi
 .PP
 .SS "bool InspSocket::OnDataReady ()\fC [virtual]\fP"
 .PP
-Definition at line 261 of file socket.cpp.
+When there is data waiting to be read on a socket, the \fBOnDataReady()\fP method is called. 
+.PP
+Within this method, you *MUST* call the \fBRead()\fP method to read any pending data. At its lowest level, this event is signalled by the core via the socket engine. If you return false from this function, the core removes your socket from its list and erases it from the socket engine, then calls \fBInspSocket::Close()\fP and deletes it. 
+.PP
+\fBReturns:\fP
+.RS 4
+false to close the socket
+.RE
+.PP
+
+.PP
+Definition at line 265 of file socket.cpp.
 .PP
 Referenced by Poll().
 .PP
 .nf
-261 { return true; }
+265 { return true; }
 .fi
 .PP
 .SS "int InspSocket::OnDisconnect ()\fC [virtual]\fP"
 .PP
-Definition at line 259 of file socket.cpp.
+When an established connection is terminated, the OnDisconnect method is triggered. 
+.PP
+Definition at line 263 of file socket.cpp.
 .PP
 .nf
-259 { return 0; }
+263 { return 0; }
 .fi
 .PP
 .SS "void InspSocket::OnError (\fBInspSocketError\fP e)\fC [virtual]\fP"
 .PP
-Definition at line 258 of file socket.cpp.
+This method is called when an error occurs. 
+.PP
+A closed socket in itself is not an error, however errors also generate close events. 
 .PP
-Referenced by InspSocket(), and Poll().
+\fBParameters:\fP
+.RS 4
+\fIe\fP The error type which occured
+.RE
+.PP
+
+.PP
+Definition at line 262 of file socket.cpp.
+.PP
+Referenced by InspSocket(), and Timeout().
 .PP
 .nf
-258 { return; }
+262 { return; }
 .fi
 .PP
 .SS "int InspSocket::OnIncomingConnection (int newfd, char * ip)\fC [virtual]\fP"
 .PP
-Definition at line 260 of file socket.cpp.
+If your socket is a listening socket, when a new connection comes in on the socket this method will be called. 
+.PP
+Given the new file descriptor in the parameters, and the IP, it is recommended you copy them to a new instance of your socket class, e.g.:
+.PP
+MySocket* newsocket = new MySocket(newfd,ip);
+.PP
+Once you have done this, you can then associate the new socket with the core using \fBServer::AddSocket()\fP.
+.PP
+Definition at line 264 of file socket.cpp.
 .PP
 Referenced by Poll().
 .PP
 .nf
-260 { return 0; }
+264 { return 0; }
 .fi
 .PP
 .SS "void InspSocket::OnTimeout ()\fC [virtual]\fP"
 .PP
-Definition at line 262 of file socket.cpp.
+When an outbound connection fails, and the attempt times out, you will receive this event. 
 .PP
-Referenced by Poll().
+The mthod will trigger once maxtime secons are reached (as given in the constructor) just before the socket's descriptor is closed.
+.PP
+Definition at line 266 of file socket.cpp.
+.PP
+Referenced by Timeout().
 .PP
 .nf
-262 { return; }
+266 { return; }
 .fi
 .PP
 .SS "bool InspSocket::Poll ()"
 .PP
-Definition at line 197 of file socket.cpp.
+Only the core should call this function. 
+.PP
+When called, it is assumed the socket is ready to read data, and the method call routes the event to the various methods of InspSocket for you to handle. This can also cause the socket's state to change.
 .PP
-References SocketEngine::AddFd(), client, SocketEngine::DelFd(), I_CONNECTED, I_CONNECTING, I_ERR_TIMEOUT, I_ERROR, I_LISTENING, length, OnConnected(), OnDataReady(), OnError(), OnIncomingConnection(), OnTimeout(), SetState(), state, timeout, timeout_end, and X_ESTAB_MODULE.
+Definition at line 214 of file socket.cpp.
+.PP
+References SocketEngine::AddFd(), client, SocketEngine::DelFd(), I_CONNECTED, I_CONNECTING, I_LISTENING, length, OnConnected(), OnDataReady(), OnIncomingConnection(), SetState(), and X_ESTAB_MODULE.
 .PP
 .nf
-198 {
-199         if ((time(NULL) > timeout_end) && (this->state == I_CONNECTING))
-200         {
-201                 // for non-listening sockets, the timeout can occur
-202                 // which causes termination of the connection after
-203                 // the given number of seconds without a successful
-204                 // connection.
-205                 this->OnTimeout();
-206                 this->OnError(I_ERR_TIMEOUT);
-207                 timeout = true;
-208                 this->state = I_ERROR;
-209                 return false;
-210         }
-211 
-212         int incoming = -1;
-213         
-214         switch (this->state)
-215         {
-216                 case I_CONNECTING:
-217                         this->SetState(I_CONNECTED);
-218                         /* Our socket was in write-state, so delete it and re-add it
-219                          * in read-state.
-220                          */
-221                         SE->DelFd(this->fd);
-222                         SE->AddFd(this->fd,true,X_ESTAB_MODULE);
-223                         return this->OnConnected();
-224                 break;
-225                 case I_LISTENING:
-226                         length = sizeof (client);
-227                         incoming = accept (this->fd, (sockaddr*)&client,&length);
-228                         this->OnIncomingConnection(incoming,inet_ntoa(client.sin_addr));
-229                         return true;
-230                 break;
-231                 case I_CONNECTED:
-232                         return this->OnDataReady();
-233                 break;
-234                 default:
-235                 break;
-236         }
-237 
-238         return true;
-239 }
+215 {
+216         int incoming = -1;
+217         
+218         switch (this->state)
+219         {
+220                 case I_CONNECTING:
+221                         this->SetState(I_CONNECTED);
+222                         /* Our socket was in write-state, so delete it and re-add it
+223                          * in read-state.
+224                          */
+225                         SE->DelFd(this->fd);
+226                         SE->AddFd(this->fd,true,X_ESTAB_MODULE);
+227                         return this->OnConnected();
+228                 break;
+229                 case I_LISTENING:
+230                         length = sizeof (client);
+231                         incoming = accept (this->fd, (sockaddr*)&client,&length);
+232                         this->OnIncomingConnection(incoming,inet_ntoa(client.sin_addr));
+233                         return true;
+234                 break;
+235                 case I_CONNECTED:
+236                         return this->OnDataReady();
+237                 break;
+238                 default:
+239                 break;
+240         }
+241 
+242         return true;
+243 }
 .fi
 .PP
 .SS "char * InspSocket::Read ()\fC [virtual]\fP"
 .PP
+Reads all pending bytes from the socket into a char* array which can be up to 16 kilobytes in length. 
+.PP
 Definition at line 155 of file socket.cpp.
 .PP
 References DEBUG, and ibuf.
@@ -444,21 +556,69 @@ References DEBUG, and ibuf.
 .PP
 .SS "void InspSocket::SetState (\fBInspSocketState\fP s)"
 .PP
-Definition at line 241 of file socket.cpp.
+Changes the socket's state. 
+.PP
+The core uses this to change socket states, and you should not call it directly.
+.PP
+Definition at line 245 of file socket.cpp.
 .PP
 References DEBUG, and state.
 .PP
 Referenced by Poll().
 .PP
 .nf
-242 {
-243         log(DEBUG,'Socket state change');
-244         this->state = s;
-245 }
+246 {
+247         log(DEBUG,'Socket state change');
+248         this->state = s;
+249 }
+.fi
+.PP
+.SS "bool InspSocket::Timeout (time_t current)"
+.PP
+This function checks if the socket has timed out yet, given the current time in the parameter. 
+.PP
+\fBReturns:\fP
+.RS 4
+true if timed out, false if not timed out
+.RE
+.PP
+
+.PP
+Definition at line 197 of file socket.cpp.
+.PP
+References I_CONNECTING, I_ERR_TIMEOUT, I_ERROR, OnError(), OnTimeout(), state, timeout, and timeout_end.
+.PP
+.nf
+198 {
+199         if ((this->state == I_CONNECTING) && (current > timeout_end))
+200         {
+201                 // for non-listening sockets, the timeout can occur
+202                 // which causes termination of the connection after
+203                 // the given number of seconds without a successful
+204                 // connection.
+205                 this->OnTimeout();
+206                 this->OnError(I_ERR_TIMEOUT);
+207                 timeout = true;
+208                 this->state = I_ERROR;
+209                 return true;
+210         }
+211         return false;
+212 }
 .fi
 .PP
 .SS "int InspSocket::Write (\fBstd::string\fP data)\fC [virtual]\fP"
 .PP
+Writes a \fBstd::string\fP to the socket. 
+.PP
+No carriage returns or linefeeds are appended to the string. 
+.PP
+\fBParameters:\fP
+.RS 4
+\fIdata\fP The data to send
+.RE
+.PP
+
+.PP
 Definition at line 174 of file socket.cpp.
 .PP
 .nf
@@ -489,66 +649,91 @@ Definition at line 174 of file socket.cpp.
 .PP 
 .SS "sockaddr_in \fBInspSocket::addr\fP\fC [private]\fP"
 .PP
-Definition at line 37 of file socket.h.
+The host being connected to, in sockaddr form. 
+.PP
+Definition at line 78 of file socket.h.
 .PP
 Referenced by InspSocket().
 .SS "in_addr \fBInspSocket::addy\fP\fC [private]\fP"
 .PP
-Definition at line 38 of file socket.h.
+The host being connected to, in in_addr form. 
+.PP
+Definition at line 84 of file socket.h.
 .PP
 Referenced by InspSocket().
 .SS "sockaddr_in \fBInspSocket::client\fP\fC [private]\fP"
 .PP
-Definition at line 44 of file socket.h.
+Client sockaddr structure used by accept(). 
+.PP
+Definition at line 119 of file socket.h.
 .PP
 Referenced by Poll().
 .SS "int \fBInspSocket::fd\fP\fC [private]\fP"
 .PP
-Definition at line 33 of file socket.h.
+The file descriptor of this socket. 
+.PP
+Definition at line 54 of file socket.h.
 .PP
 Referenced by Close(), GetFd(), and InspSocket().
 .SS "\fBstd::string\fP \fBInspSocket::host\fP\fC [private]\fP"
 .PP
-Definition at line 34 of file socket.h.
+The hostname connected to. 
+.PP
+Definition at line 59 of file socket.h.
 .SS "char \fBInspSocket::ibuf\fP[16384]\fC [private]\fP"
 .PP
-Definition at line 42 of file socket.h.
+Socket input buffer, used by read(). 
+.PP
+The class which extends InspSocket is expected to implement an extendable buffer which can grow much larger than 16k, this buffer is just designed to be temporary storage. space.
+.PP
+Definition at line 106 of file socket.h.
 .PP
 Referenced by Read().
 .SS "\fBstd::string\fP \fBInspSocket::IP\fP\fC [private]\fP"
 .PP
-Definition at line 43 of file socket.h.
+The IP address being connected to stored in string form for easy retrieval by accessors. 
+.PP
+Definition at line 113 of file socket.h.
 .PP
 Referenced by GetIP(), and InspSocket().
 .SS "socklen_t \fBInspSocket::length\fP\fC [private]\fP"
 .PP
-Definition at line 46 of file socket.h.
+Used by accept() to indicate the sizes of the sockaddr_in structures. 
 .PP
-Referenced by Poll().
-.SS "pollfd \fBInspSocket::polls\fP\fC [private]\fP"
+Definition at line 131 of file socket.h.
 .PP
-Definition at line 41 of file socket.h.
+Referenced by Poll().
 .SS "int \fBInspSocket::port\fP\fC [private]\fP"
 .PP
-Definition at line 35 of file socket.h.
+The port connected to, or the port this socket is listening on. 
+.PP
+Definition at line 65 of file socket.h.
 .SS "sockaddr_in \fBInspSocket::server\fP\fC [private]\fP"
 .PP
-Definition at line 45 of file socket.h.
+\fBServer\fP sockaddr structure used by accept(). 
+.PP
+Definition at line 125 of file socket.h.
 .SS "\fBInspSocketState\fP \fBInspSocket::state\fP\fC [private]\fP"
 .PP
-Definition at line 36 of file socket.h.
+The state for this socket, either listening, connecting, connected or error. 
 .PP
-Referenced by GetState(), InspSocket(), Poll(), and SetState().
+Definition at line 72 of file socket.h.
+.PP
+Referenced by GetState(), InspSocket(), SetState(), and Timeout().
 .SS "bool \fBInspSocket::timeout\fP\fC [private]\fP"
 .PP
-Definition at line 40 of file socket.h.
+This value is true if the socket has timed out. 
+.PP
+Definition at line 97 of file socket.h.
 .PP
-Referenced by InspSocket(), and Poll().
+Referenced by InspSocket(), and Timeout().
 .SS "time_t \fBInspSocket::timeout_end\fP\fC [private]\fP"
 .PP
-Definition at line 39 of file socket.h.
+When this time is reached, the socket times out if it is in the CONNECTING state. 
+.PP
+Definition at line 91 of file socket.h.
 .PP
-Referenced by InspSocket(), and Poll().
+Referenced by InspSocket(), and Timeout().
 
 .SH "Author"
 .PP 
diff --git a/docs/man/man3/SocketEngine.3 b/docs/man/man3/SocketEngine.3
index 299dff3f4..232d8f8cd 100644
--- a/docs/man/man3/SocketEngine.3
+++ b/docs/man/man3/SocketEngine.3
@@ -287,7 +287,7 @@ References DEBUG, EngineHandle, fds, ke_list, ref, ts, and X_READBIT.
 164                 
 165         }
 166         tval.tv_sec = 0;
-167         tval.tv_usec = 1000L;
+167         tval.tv_usec = 100L;
 168         sresult = select(FD_SETSIZE, &rfdset, &wfdset, NULL, &tval);
 169         if (sresult > 0)
 170         {
@@ -302,14 +302,14 @@ References DEBUG, EngineHandle, fds, ke_list, ref, ts, and X_READBIT.
 179         }
 180 #endif
 181 #ifdef USE_KQUEUE
-182         ts.tv_nsec = 1000L;
+182         ts.tv_nsec = 10000L;
 183         ts.tv_sec = 0;
 184         int i = kevent(EngineHandle, NULL, 0, &ke_list[0], 65535, &ts);
 185         for (int j = 0; j < i; j++)
 186                 fdlist.push_back(ke_list[j].ident);
 187 #endif
 188 #ifdef USE_EPOLL
-189         int i = epoll_wait(EngineHandle, events, 65535, 1);
+189         int i = epoll_wait(EngineHandle, events, 65535, 100);
 190         for (int j = 0; j < i; j++)
 191                 fdlist.push_back(events[j].data.fd);
 192 #endif
diff --git a/docs/man/man3/chanrec.3 b/docs/man/man3/chanrec.3
index f6e50a153..c02b05305 100644
--- a/docs/man/man3/chanrec.3
+++ b/docs/man/man3/chanrec.3
@@ -154,15 +154,15 @@ Add a user pointer to the internal reference list.
 .PP
 The data inserted into the reference list is a table as it is an arbitary pointer compared to other users by its memory address, as this is a very fast 32 or 64 bit integer comparison.
 .PP
-Definition at line 195 of file channels.cpp.
+Definition at line 194 of file channels.cpp.
 .PP
 References DEBUG, and internal_userlist.
 .PP
 .nf
-196 {
-197         internal_userlist.push_back(castuser);
-198         log(DEBUG,'Added casted user to channel's internal list');
-199 }
+195 {
+196         internal_userlist.push_back(castuser);
+197         log(DEBUG,'Added casted user to channel's internal list');
+198 }
 .fi
 .PP
 .SS "void chanrec::DelUser (char * castuser)"
@@ -176,23 +176,23 @@ Delete a user pointer to the internal reference list.
 .PP
 The data removed from the reference list is a table as it is an arbitary pointer compared to other users by its memory address, as this is a very fast 32 or 64 bit integer comparison.
 .PP
-Definition at line 201 of file channels.cpp.
+Definition at line 200 of file channels.cpp.
 .PP
 References DEBUG, internal_userlist, and name.
 .PP
 .nf
-202 {
-203         for (std::vector<char*>::iterator a = internal_userlist.begin(); a < internal_userlist.end(); a++)
-204         {
-205                 if (*a == castuser)
-206                 {
-207                         log(DEBUG,'Removed casted user from channel's internal list');
-208                         internal_userlist.erase(a);
-209                         return;
-210                 }
-211         }
-212         log(DEBUG,'BUG BUG BUG! Attempt to remove an uncasted user from the internal list of %s!',name);
-213 }
+201 {
+202         for (std::vector<char*>::iterator a = internal_userlist.begin(); a < internal_userlist.end(); a++)
+203         {
+204                 if (*a == castuser)
+205                 {
+206                         log(DEBUG,'Removed casted user from channel's internal list');
+207                         internal_userlist.erase(a);
+208                         return;
+209                 }
+210         }
+211         log(DEBUG,'BUG BUG BUG! Attempt to remove an uncasted user from the internal list of %s!',name);
+212 }
 .fi
 .PP
 .SS "\fBstd::string\fP chanrec::GetModeParameter (char mode)"
@@ -213,24 +213,24 @@ The parameter for this mode is returned, or an empty string
 .PP
 
 .PP
-Definition at line 175 of file channels.cpp.
+Definition at line 174 of file channels.cpp.
 .PP
 References custom_mode_params.
 .PP
 .nf
-176 {
-177         if (custom_mode_params.size())
-178         {
-179                 for (vector<ModeParameter>::iterator i = custom_mode_params.begin(); i < custom_mode_params.end(); i++)
-180                 {
-181                         if ((i->mode == mode) && (!strcasecmp(this->name,i->channel)))
-182                         {
-183                                 return i->parameter;
-184                         }
-185                 }
-186         }
-187         return '';
-188 }
+175 {
+176         if (custom_mode_params.size())
+177         {
+178                 for (vector<ModeParameter>::iterator i = custom_mode_params.begin(); i < custom_mode_params.end(); i++)
+179                 {
+180                         if ((i->mode == mode) && (!strcasecmp(this->name,i->channel)))
+181                         {
+182                                 return i->parameter;
+183                         }
+184                 }
+185         }
+186         return '';
+187 }
 .fi
 .PP
 .SS "long chanrec::GetUserCounter ()"
@@ -244,12 +244,12 @@ The number of users on this channel
 .PP
 
 .PP
-Definition at line 190 of file channels.cpp.
+Definition at line 189 of file channels.cpp.
 .PP
 .nf
-191 {
-192         return (this->internal_userlist.size());
-193 }
+190 {
+191         return (this->internal_userlist.size());
+192 }
 .fi
 .PP
 .SS "std::vector< char * > * chanrec::GetUsers ()"
@@ -265,16 +265,16 @@ This function returns a vector of userrec pointers, each of which has been caste
 .PP
 
 .PP
-Definition at line 215 of file channels.cpp.
+Definition at line 214 of file channels.cpp.
 .PP
 References internal_userlist.
 .PP
 Referenced by Server::GetUsers().
 .PP
 .nf
-216 {
-217         return &internal_userlist;
-218 }
+215 {
+216         return &internal_userlist;
+217 }
 .fi
 .PP
 .SS "bool chanrec::IsCustomModeSet (char mode)"
@@ -295,13 +295,10 @@ True if the custom mode is set, false if otherwise
 .PP
 Definition at line 169 of file channels.cpp.
 .PP
-References DEBUG.
-.PP
 .nf
 170 {
-171         log(DEBUG,'Checking ISCustomModeSet: %c %s',mode,this->custom_modes);
-172         return (strchr(this->custom_modes,mode) != 0);
-173 }
+171         return (strchr(this->custom_modes,mode));
+172 }
 .fi
 .PP
 .SS "void chanrec::SetCustomMode (char mode, bool mode_on)"
diff --git a/docs/man/man3/modules.h.3 b/docs/man/man3/modules.h.3
index 928941c19..3c43187ac 100644
--- a/docs/man/man3/modules.h.3
+++ b/docs/man/man3/modules.h.3
@@ -262,7 +262,7 @@ log levels
 .PP
 Definition at line 23 of file modules.h.
 .PP
-Referenced by Server::AddExtendedMode(), SocketEngine::AddFd(), chanrec::AddUser(), SocketEngine::DelFd(), chanrec::DelUser(), InspSocket::InspSocket(), chanrec::IsCustomModeSet(), InspSocket::Read(), userrec::ReadData(), userrec::RemoveInvite(), chanrec::SetCustomMode(), chanrec::SetCustomModeParam(), InspSocket::SetState(), userrec::SetWriteError(), SocketEngine::SocketEngine(), SocketEngine::Wait(), and SocketEngine::~SocketEngine().
+Referenced by Server::AddExtendedMode(), SocketEngine::AddFd(), chanrec::AddUser(), SocketEngine::DelFd(), chanrec::DelUser(), InspSocket::InspSocket(), InspSocket::Read(), userrec::ReadData(), userrec::RemoveInvite(), chanrec::SetCustomMode(), chanrec::SetCustomModeParam(), InspSocket::SetState(), userrec::SetWriteError(), SocketEngine::SocketEngine(), SocketEngine::Wait(), and SocketEngine::~SocketEngine().
 .SS "#define DEFAULT   30"
 .PP
 Definition at line 25 of file modules.h.
diff --git a/docs/man/man3/socket.h.3 b/docs/man/man3/socket.h.3
index 89e2a1c07..3810efe1d 100644
--- a/docs/man/man3/socket.h.3
+++ b/docs/man/man3/socket.h.3
@@ -12,8 +12,6 @@ socket.h \-
 .br
 \fC#include <netinet/in.h>\fP
 .br
-\fC#include <poll.h>\fP
-.br
 \fC#include <sstream>\fP
 .br
 \fC#include <string>\fP
@@ -25,6 +23,7 @@ socket.h \-
 .ti -1c
 .RI "class \fBInspSocket\fP"
 .br
+.RI "\fIInspSocket is an extendable socket class which modules can use for TCP socket support. \fP"
 .in -1c
 .SS "Enumerations"
 
@@ -32,14 +31,18 @@ socket.h \-
 .ti -1c
 .RI "enum \fBInspSocketState\fP { \fBI_DISCONNECTED\fP, \fBI_CONNECTING\fP, \fBI_CONNECTED\fP, \fBI_LISTENING\fP, \fBI_ERROR\fP }"
 .br
+.RI "\fIStates which a socket may be in. \fP"
 .ti -1c
 .RI "enum \fBInspSocketError\fP { \fBI_ERR_TIMEOUT\fP, \fBI_ERR_SOCKET\fP, \fBI_ERR_CONNECT\fP, \fBI_ERR_BIND\fP }"
 .br
+.RI "\fIError types which a socket may exhibit. \fP"
 .in -1c
 .SH "Enumeration Type Documentation"
 .PP 
 .SS "enum \fBInspSocketError\fP"
 .PP
+Error types which a socket may exhibit. 
+.PP
 \fBEnumerator: \fP
 .in +1c
 .TP
@@ -52,14 +55,16 @@ socket.h \-
 \fB\fII_ERR_BIND \fP\fP
 
 .PP
-Definition at line 28 of file socket.h.
+Definition at line 34 of file socket.h.
 .PP
 .nf
-28 { I_ERR_TIMEOUT, I_ERR_SOCKET, I_ERR_CONNECT, I_ERR_BIND };
+34 { I_ERR_TIMEOUT, I_ERR_SOCKET, I_ERR_CONNECT, I_ERR_BIND };
 .fi
 .PP
 .SS "enum \fBInspSocketState\fP"
 .PP
+States which a socket may be in. 
+.PP
 \fBEnumerator: \fP
 .in +1c
 .TP
@@ -74,10 +79,10 @@ Definition at line 28 of file socket.h.
 \fB\fII_ERROR \fP\fP
 
 .PP
-Definition at line 27 of file socket.h.
+Definition at line 29 of file socket.h.
 .PP
 .nf
-27 { I_DISCONNECTED, I_CONNECTING, I_CONNECTED, I_LISTENING, I_ERROR };
+29 { I_DISCONNECTED, I_CONNECTING, I_CONNECTED, I_LISTENING, I_ERROR };
 .fi
 .PP
 .SH "Author"