Merge pull request #184 from CIB/documentation

Added doxygen comments

Core/Contents/Include/PolyPeer.h

@@ -69,26 +69,78 @@ namespace Polycode {
 		std::vector<unsigned short> recentReliableIDs;
 		Address address;
 	};
-		
+
+	/** 
+	* A network actor that can send and receive data.
+	*
+	* Peers are comparable to UDP sockets, but with extended functionality
+	* to optionally allow for some of TCP's features(ordering, reliability).
+	*
+	* WARNING: Reliability(packets being resent on loss) is currently not
+	* implemented, but is planned.
+	*
+	* @see PeerConnection
+	*/
 #if USE_THREADED_SOCKETS == 1		
 	class _PolyExport Peer : public Threaded {
 #else
 	class _PolyExport Peer : public EventDispatcher {
 #endif
 		public:
+			/**
+			* Create a peer. The peer will immediately start listening on the given 
+			* port and accept incoming packets.
+			*
+			* @param port The UDP port to listen for packets. Can not be omitted,
+			*             this will be the actual port this peer will use to send
+			*             and receive packets.
+			*/
 			Peer(unsigned int port);
 			~Peer();
-		
+
 			void handleEvent(Event *event);
 
 			virtual void handlePacket(Packet *packet, PeerConnection *connection){};
 			virtual void handlePeerConnection(PeerConnection *connection){};
 		
 			Packet *createPacket(const Address &target, char *data, unsigned int size, unsigned short type);
-
+			
+			/**
+			* Send raw binary data to the target address.
+			*
+			* @param target The network Address to send the data to.
+			* @param data The binary data to send as a C byte array. Length must be supplied by size parameter.
+			* @param size The size in bytes of the sent binary data.
+			* @param type A number representing the packet type, used to define the purpose of the packet.
+			*/
 			void sendData(const Address &target, char *data, unsigned int size, unsigned short type);
+
+			/**
+			* Send raw binary data to the target address, making sure it arrives in the right order.
+			*
+			* @param target The network address to send the data to.
+			* @param data The binary data to send as a C byte array. Length must be supplied by size parameter.
+			* @param size The size in bytes of the sent binary data.
+			* @param type A number representing the packet type, used to define the purpose of the packet.
+			*/
 			void sendReliableData(const Address &target, char *data, unsigned int size, unsigned short type);
+
+			/**
+			* Broadcast raw binary data to all connected peers, making sure it arrives in the right order.
+			*
+			* @param data The binary data to send as a C byte array. Length must be supplied by size parameter.
+			* @param size The size in bytes of the sent binary data.
+			* @param type A number representing the packet type, used to define the purpose of the packet.
+			*/
 			void sendReliableDataToAll(char *data, unsigned int size, unsigned short type);
+
+			/**
+			* Broadcast raw binary data to all connected peers.
+			*
+			* @param data The binary data to send as a C byte array. Length must be supplied by size parameter.
+			* @param size The size in bytes of the sent binary data.
+			* @param type A number representing the packet type, used to define the purpose of the packet.
+			*/
 			void sendDataToAll(char *data, unsigned int size, unsigned short type);		
 		
 			void sendPacket(const Address &target, Packet *packet);

Core/Contents/Include/PolyServer.h

@@ -70,20 +70,52 @@ namespace Polycode {
 		// Notice also the SERVERCLIENTEVENT above, which starts with 0x780.
 	};
 
+	/** 
+	* A network server, accepting incoming connections and keeping track of connected clients.
+	*
+	* As the Peer class already provides all connectivity functionality required, the Server class
+	* merely provides another abstraction layer to treat clients separately from mere connections.
+	*
+	* The Server will process incoming packets N times per second, where N is an argument to the constructor.
+	* This means you can coordinate the server's reaction time to your program's internal timer.
+	*/
 	class _PolyExport Server : public Peer {
 		public:
+			/**
+			* Constructor.
+			* @param port The port to listen for client connections on.
+			* @param rate How many times per second this instance should check for new incoming packets.
+			* @param world A singleton which manages the "world" this network server is attached to.
+			*/
 			Server(unsigned int port, unsigned int rate, ServerWorld *world = NULL);
 			~Server();
 		
-			void DisconnectClient(ServerClient *client);
-			void handleEvent(Event *event);		
+			void handlePacket(Packet *packet, PeerConnection *connection);
+			void handleEvent(Event *event);	
 			void handlePeerConnection(PeerConnection *connection);
+
+			/**
+			* Callback handler invoked when a client disconnects.
+			* @param client The client that disconnected.
+			*/
+			void DisconnectClient(ServerClient *client);
+
+			/**
+			* Get a connected client from its associated peer connection, if any.
+			* @param connection The PeerConnection through which we're communicating 
+			*                   with the client to obtain.
+			*/
 			ServerClient *getConnectedClient(PeerConnection *connection);
 		
+			/**
+			* @see Peer::sendReliableData
+			*/
 			void sendReliableDataToClient(ServerClient *client, char *data, unsigned int size, unsigned short type);
+
+			/**
+			* @see Peer::sendReliableDataToAll
+			*/
 			void sendReliableDataToAllClients(char *data, unsigned int size, unsigned short type);
-					
-			void handlePacket(Packet *packet, PeerConnection *connection);
 		
 	protected:
 		

Core/Contents/Include/PolySocket.h

@@ -59,29 +59,87 @@ THE SOFTWARE.
 #endif
 
 namespace Polycode {
-		
+
+	/**
+	* A typical network address, defined by IP and port.
+	*/
 	class _PolyExport Address  {
 		public:
+
+		/**
+		* Constructor.
+		* @param ipAsString An IP address represented as string,
+		*                   for example "197.0.0.1"
+		* @param port The UDP/TCP port of the address, given in
+		*             host byte order.
+		*/
 		Address(String ipAsString, unsigned int port);
+
+		/**
+		* Constructor.
+		* @param ip An IP address given as integer in host byte
+		*           order.
+		* @param port The UDP/TCP port of the address, given in
+		*             host byte order.
+		*/
 		Address(unsigned int ip, unsigned int port);
+
+		/**
+		* Constructor, leaving the address uninitalized.
+		*
+		* Address IP and port will default to 0.
+		*/
 		Address();
 		~Address();
 		
+		/**
+		* Copy the address IP and port from add2 into this.
+		* @param add2 The address to copy into this.
+		*/
 		inline void operator = (const Address &add2) {
 			setAddress(add2.uintAddress, add2.port);
 		}
 		
+		/**
+		* @return 1 if the address IP and port match, 0 otherwise.
+		*/
 		inline bool operator == ( const Address& add2)  {
 			return (uintAddress == add2.uintAddress && port == add2.port);
 		}
 			
-		
+		/**
+		* Update the address IP and port.
+		* @param ipAsString An IP address represented as string,
+		*                   for example "197.0.0.1"
+		* @param port The UDP/TCP port of the address, given in
+		*             host byte order.
+		*/
 		void setAddress(String ipAsString, unsigned int port);
+
+		/**
+		* Update the address IP and port.
+		* @param ip An IP address given as integer in host byte
+		*           order.
+		* @param port The UDP/TCP port of the address, given in
+		*             host byte order.
+		*/
 		void setAddress(unsigned int ip, unsigned int port);
 		
+		// TODO: A way to get the IP/port without exposing internal members.
+		//       The problem here is that the IP internally is converted to
+		//       network byte order, but the API seems to work with host byte
+		//       order, so I'm unsure in which byte order the IP/port should
+		//       be returned.
+
+		protected:
 		unsigned int uintAddress;
 		unsigned int port;
-		sockaddr_in sockAddress;		
+
+		sockaddr_in sockAddress;
+
+		// This class already uses socket API structs internally,
+		// so it's no far stretch to make it tied to the Socket class.
+		friend class Socket;
 	};
 	
 	

Core/Contents/Source/PolySocket.cpp

@@ -38,8 +38,7 @@ Address::Address(unsigned int ip, unsigned int port) {
 	setAddress(ip, port);
 }
 
-Address::Address() {
-	
+Address::Address()  : uintAddress(0), port(0) {
 }
 
 void Address::setAddress(unsigned int ip, unsigned int port) {