Revision 8:9cf9c2d45264, committed 2012-07-27

Comitter:

emilmont

Date:

Fri Jul 27 15:50:23 2012 +0000

Parent:

7:ac5f77f4497a

Child:

9:f972715add36

Commit message:

Update documentation

Changed in this revision

--- a/Endpoint.h	Fri Jul 27 14:22:45 2012 +0000
+++ b/Endpoint.h	Fri Jul 27 15:50:23 2012 +0000
@@ -18,18 +18,38 @@
 #ifndef ENDPOINT_H
 #define ENDPOINT_H
 
+/**
+IP Endpoint (address, port)
+*/
 class Endpoint {
 
 public:
+    /** IP Endpoint (address, port)
+     */
     Endpoint(void);
     
     ~Endpoint(void);
     
+    /** Reset the address of this endpoint
+     */
     void reset_address(void);
+    
+    /** Set the address of this endpoint
+    \param host The endpoint address (it can either be an IP Address or a hostname that will be resolved with DNS).
+    \param port The endpoint port
+    \return 0 on success, -1 on failure (when an hostname cannot be resolved by DNS).
+     */
     int  set_address(const char* host, const int port);
     
+    /** Get the IP address of this endpoint
+    \return The IP address of this endpoint.
+     */
     char* get_address(void);
-    int   get_port(void);
+    
+    /** Get the port of this endpoint
+    \return The port of this endpoint
+     */
+    int get_port(void);
 
 protected:
     char _ipAddress[16];

--- a/Socket.h	Fri Jul 27 14:22:45 2012 +0000
+++ b/Socket.h	Fri Jul 27 15:50:23 2012 +0000
@@ -32,10 +32,16 @@
 
 class TimeInterval;
 
+/** Socket file descriptor and select wrapper
+  */
 class Socket {
 public:
+    /** Socket
+     */
     Socket();
     
+    /** Close the socket file descriptor
+     */
     int close();
     
 protected:
@@ -49,10 +55,15 @@
     int select(struct timeval *timeout, bool read, bool write);
 };
 
+/** Time interval class used to specify timeouts
+ */
 class TimeInterval {
     friend class Socket;
 
 public:
+    /** Time Interval
+     \param ms time interval expressed in milliseconds
+      */
     TimeInterval(int ms);
     
 private:

--- a/TCPSocketConnection.h	Fri Jul 27 14:22:45 2012 +0000
+++ b/TCPSocketConnection.h	Fri Jul 27 15:50:23 2012 +0000
@@ -23,19 +23,19 @@
 #include "Socket/Endpoint.h"
 
 /**
-This is a C++ abstraction for TCP networking sockets.
+TCP socket connection
 */
 class TCPSocketConnection : public Socket, public Endpoint {
     friend class TCPSocketServer;
     
 public:
-    /** Instantiate a TCP Socket.
+    /** TCP socket connection
     */
     TCPSocketConnection();
     
     ~TCPSocketConnection();
     
-    /** Connect the TCP Socket to the following host.
+    /** Connects this TCP socket to the server
     \param host The host to connect to. It can either be an IP Address or a hostname that will be resolved with DNS.
     \param port The host's port to connect to.
     \return 0 on success, -1 on failure.
@@ -45,12 +45,12 @@
     /** Send data to the remote host.
     \param data The buffer to send to the host.
     \param length The length of the buffer to send.
-    \param timeout The maximum amount of time in ms to wait while trying to send the buffer.
+    \param timeout_ms The maximum amount of time in ms to wait while trying to send the buffer.
     \return the number of written bytes on success (>=0) or -1 on failure
      */
     int send(char* data, int length, int timeout_ms=0);
     
-    /** Send data to the remote host.
+    /** Send all the data to the remote host.
     \param data The buffer to send to the host.
     \param length The length of the buffer to send.
     \param timeout The maximum amount of time in ms to wait while trying to send the buffer.
@@ -66,10 +66,10 @@
      */
     int receive(char* data, int length, int timeout_ms=0);
     
-    /** Receive data from the remote host.
+    /** Receive all the data from the remote host.
     \param data The buffer in which to store the data received from the host.
     \param length The maximum length of the buffer.
-    \param timeout The maximum amount of time in ms to wait while trying to receive data.
+    \param timeout_ms The maximum amount of time in ms to wait while trying to receive data.
     \return the number of received bytes on success (>=0) or -1 on failure
     */
     int receive_all(char* data, int length, int timeout_ms=0);

--- a/TCPSocketServer.h	Fri Jul 27 14:22:45 2012 +0000
+++ b/TCPSocketServer.h	Fri Jul 27 15:50:23 2012 +0000
@@ -21,29 +21,31 @@
 #include "Socket/Socket.h"
 #include "TCPSocketConnection.h"
 
+/** TCP Server.
+  */
 class TCPSocketServer : Socket {
   public:
-    /** Instantiate a TCP Socket.
+    /** Instantiate a TCP Server.
     */
     TCPSocketServer();
     
     ~TCPSocketServer();
     
     /** Bind a socket to a specific port.
-    For a listening socket, bind the socket to the following port. The socket will start listening for incoming connections on this port on the call to listen().
     \param port The port to listen for incoming connections on.
     \return 0 on success, -1 on failure.
     */
     int bind(int port);
-
+    
     /** Start listening for incoming connections.
-    \param max The maximum number of connections that can be accepted.
+    \param backlog number of pending connections that can be queued up at any one time.
     \return 0 on success, -1 on failure.
     */
-    int listen(int max);
-
+    int listen(int backlog);
+    
     /** Accept a new connection.
-    \param socket A socket instance that will handle the incoming connection.
+    \param connection A TCPSocketConnection instance that will handle the incoming connection.
+    \param timeout_ms The maximum amount of time in ms to wait for a new connection.
     \return 0 on success, -1 on failure.
     */
     int accept(TCPSocketConnection& connection, int timeout_ms=0);

--- a/UDPPacket.h	Fri Jul 27 14:22:45 2012 +0000
+++ b/UDPPacket.h	Fri Jul 27 15:50:23 2012 +0000
@@ -24,13 +24,23 @@
 // Forward declaration
 class UDPSocket;
 
+/** UDP Packet
+  */
 class UDPPacket : public Endpoint {
     friend class UDPSocket;
 
 public:
+    /** UDP Packet
+      \param buffer   Pointer to the data buffer for this packet
+      \param length   length of the data buffer
+      */
     UDPPacket(char* buffer, unsigned int length);
     ~UDPPacket() {}
     
+    /** Set the data buffer for this packet
+      \param buffer   Pointer to the data buffer for this packet
+      \param length   length of the data buffer
+      */
     void set_data(char* buffer, unsigned int length);
 
 private:

--- a/UDPSocket.h	Fri Jul 27 14:22:45 2012 +0000
+++ b/UDPSocket.h	Fri Jul 27 15:50:23 2012 +0000
@@ -24,29 +24,31 @@
 #include <cstdint>
 
 /**
-This is a C++ abstraction for UDP networking sockets.
+UDP Socket
 */
 class UDPSocket : public Socket {
 
 public:
-    /** Instantiate a UDP Socket.
+    /** Instantiate an UDP Socket.
     */
     UDPSocket();
     
     ~UDPSocket();
     
+    /** Init the UDP Client Socket without binding it to any specific port
+    \return 0 on success, -1 on failure.
+    */
     int init(void);
     
     /** Bind a UDP Server Socket to a specific port
-    For a listening socket, bind the socket to the following port.
-    \param port The port to listen for incoming connections on, using 0 here will select a random port.
+    \param port The port to listen for incoming connections on
     \return 0 on success, -1 on failure.
     */
     int bind(int port);
     
     /** Send a packet to the remote host.
     \param packet UDP Packet to be sent to the remote host
-    \param timeout The maximum amount of time in ms to wait while trying to send the buffer.
+    \param timeout_ms The maximum amount of time in ms to wait while trying to send the packet.
     \return the number of written bytes on success (>=0) or -1 on failure
     */
     int sendTo(UDPPacket& packet, int timeout_ms=0);
@@ -55,7 +57,7 @@
     If a message is too long to fit in the supplied packet, excess bytes are
     discarded.
     \param packet UDP Packet received from the remote host
-    \param timeout The maximum amount of time in ms to wait while trying to receive data.
+    \param timeout The maximum amount of time in ms to wait while trying to receive packet.
     \return the number of received bytes on success (>=0) or -1 on failure
     */
     int receiveFrom(UDPPacket& packet, int timeout_ms=0);