adding comments

git-svn-id: svn+ssh://svn.code.sf.net/p/supertuxkart/code/main/branches/hilnius@14123 178a84e3-b1eb-0310-8ba1-8eac791a3b58

src/network/client_network_manager.hpp

@@ -52,10 +52,22 @@ class ClientNetworkManager : public NetworkManager
          *  \param reliable : If set to true, ENet will ensure that the packet is received.
          */
         virtual void sendPacket(const NetworkString& data, bool reliable = true);
-
+        
+        /*! \brief Get the peer (the server)
+         *  \return The peer with whom we're connected (if it exists). NULL elseway.
+         */
         STKPeer* getPeer();
+        /*! \brief Function to know if we're a server.
+         *  \return Returns true if we're on a server. False if we're a client.
+         */
         virtual bool isServer()         { return false; }
+        /*! \brief Function used to notice the manager that we're connected to a server.
+         *  \param value : True if we're connected, false elseway.
+         */
         void setConnected(bool value)   { m_connected = value; }
+        /*! \brief Function to know if we're a server.
+         *  \return Returns true if we're on a server. False if we're a client.
+         */
         bool isConnected()              { return m_connected; }
 
     protected:
@@ -63,7 +75,7 @@ class ClientNetworkManager : public NetworkManager
         virtual ~ClientNetworkManager();
 
         bool m_connected; //!< Is the user connected to a server
-        pthread_t* m_thread_keyboard;
+        pthread_t* m_thread_keyboard; //!< The thread listening for keyboard console input.
 };
 
 #endif // CLIENT_NETWORK_MANAGER_HPP

src/network/game_setup.hpp

@@ -59,6 +59,9 @@ class GameSetup
         void setPlayerKart(uint8_t id, std::string kart_name); //!< Set the kart of a player
         void bindKartsToProfiles(); //!< Sets the right world_kart_id in profiles
 
+        /** \brief Get the players that are in the game 
+         *  \return A vector containing pointers on the players profiles.
+         */
         std::vector<NetworkPlayerProfile*> getPlayers() { return m_players; }
         int getPlayerCount() { return m_players.size(); }
         /*! \brief Get a network player profile matching a universal id.

src/network/network_manager.hpp

@@ -34,23 +34,55 @@
 
 #include <vector>
 
+/** \class NetworkManager
+ *  \brief Gives the general functions to use network communication.
+ *  This class is in charge of storing the peers connected to this host.
+ *  It also stores the host, and brings the functions to send messages to peers.
+ *  It automatically dispatches the events or packets it receives. This class 
+ *  also stores the public address when known and the player login. 
+ *  Here are defined some functions that will be specifically implemented by
+ *  the ServerNetworkManager and the ClientNetworkManager.
+ */
 class NetworkManager : public Singleton<NetworkManager>
 {
     friend class Singleton<NetworkManager>;
     public:
+        /** \brief Function to start the Network Manager (start threads) */
         virtual void run();
+        /** \brief Function to reset the Network Manager.
+         *  This function resets the peers and the listening host.
+         */
         virtual void reset();
+        /** \brief Function that aborts the NetworkManager.
+         *  This function will stop the listening, delete the host and stop
+         *  threads that are related to networking.
+         */
         virtual void abort();
 
         // network management functions
+        /** \brief Try to establish a connection to a given transport address.
+         *  \param peer : The transport address which you want to connect to.
+         *  \return True if we're successfully connected. False elseway.
+         */
         virtual bool connect(TransportAddress peer);
+        /** \brief Changes the socket working mode.
+         *  Sockets can be in two modes : The ENet mode and a mode we will call
+         *  the 'Raw' mode. In the ENet mode, the socket will be read as 
+         *  \param peer : The transport address which you want to connect to.
+         *  \return True if we're successfully connected. False elseway.
+         */
         virtual void setManualSocketsMode(bool manual);
 
         // message/packets related functions
         virtual void notifyEvent(Event* event);
-        virtual void sendPacket(const NetworkString& data, bool reliable = true) = 0;
-        virtual void sendPacket(STKPeer* peer, const NetworkString& data, bool reliable = true);
-        virtual void sendPacketExcept(STKPeer* peer, const NetworkString& data, bool reliable = true);
+        virtual void sendPacket(const NetworkString& data, 
+                                bool reliable = true) = 0;
+        virtual void sendPacket(STKPeer* peer, 
+                                const NetworkString& data, 
+                                bool reliable = true);
+        virtual void sendPacketExcept(STKPeer* peer, 
+                                const NetworkString& data, 
+                                bool reliable = true);
 
         // Game related functions
         virtual GameSetup* setupNewGame(); //!< Creates a new game setup and returns it

src/network/protocol_manager.cpp

@@ -82,8 +82,7 @@ ProtocolManager::~ProtocolManager()
 void ProtocolManager::abort()
 {
     pthread_mutex_unlock(&m_exit_mutex); // will stop the update function
-    pthread_join(*m_asynchronous_update_thread, NULL);
-
+    pthread_join(*m_asynchronous_update_thread, NULL); // wait the thread to finish
     pthread_mutex_lock(&m_events_mutex);
     pthread_mutex_lock(&m_protocols_mutex);
     pthread_mutex_lock(&m_asynchronous_protocols_mutex);

src/network/stk_host.cpp

@@ -170,8 +170,7 @@ void STKHost::stopListening()
     if(m_listening_thread)
     {
         pthread_mutex_unlock(&m_exit_mutex); // will stop the update function on its next update
-        pthread_join(*m_listening_thread, NULL); // wait the thread to end
-    }
+        pthread_join(*m_listening_thread, NULL); // wait the thread to end    }
 }
 
 // ----------------------------------------------------------------------------