doc pass

Author: gafferongames

doxygen.config

@@ -32,19 +32,19 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "libyojimbo"
+PROJECT_NAME           = "Yojimbo"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = 1.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = "Network library for client/server games"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55

yojimbo.h

@@ -604,7 +604,7 @@ namespace yojimbo
     };
 
     /**
-        Allocator implementation based on malloc and free.
+        The default allocator implementation based around malloc and free.
      */
 
     class DefaultAllocator : public Allocator
@@ -646,7 +646,7 @@ namespace yojimbo
     };
 
     /**
-        Allocator built on the TLSF allocator implementation by Matt Conte. Thanks Matt!
+        An allocator built on the TLSF allocator implementation by Matt Conte. Thanks Matt!
         This is a fast allocator that supports multiple heaps. It's used inside the yojimbo server to silo allocations for each client to their own heap.
         See https://github.com/mattconte/tlsf for details on this allocator implementation.
      */
@@ -3437,16 +3437,25 @@ namespace yojimbo
 
     /**
         A reference counted object that can be serialized to a bitstream.
+
         Messages are objects that are sent between client and server across the connection. They are carried inside the ConnectionPacket generated by the Connection class. Messages can be sent reliable-ordered, or unreliable-unordered, depending on the configuration of the channel they are sent over.
+        
         To use messages, create your own set of message classes by inheriting from this class (or from BlockMessage, if you want to attach data blocks to your message), then setup an enum of all your message types and derive a message factory class to create your message instances by type.
+        
         There are macros to help make defining your message factory painless:
+        
             YOJIMBO_MESSAGE_FACTORY_START
             YOJIMBO_DECLARE_MESSAGE_TYPE
             YOJIMBO_MESSAGE_FACTORY_FINISH
+        
         Once you have a message factory, register it with your declared inside your client and server classes using:
+        
             YOJIMBO_MESSAGE_FACTORY
+        
         which overrides the Client::CreateMessageFactory and Server::CreateMessageFactory methods so the client and server classes use your message factory type.
+        
         See tests/shared.h for an example showing you how to do this, and the functional tests inside tests/test.cpp for examples showing how how to send and receive messages.
+        
         @see BlockMessage
         @see MessageFactory
         @see Connection
@@ -3589,10 +3598,6 @@ namespace yojimbo
 
     /**
         A message which can have a block of data attached to it.
-        Attaching blocks of data is very useful, especially over a reliable-ordered channel where these blocks can be larger that the maximum packet size. Blocks sent over a reliable-ordered channel are automatically split up into fragments and reassembled on the other side.
-        This gives you have the convenience of a reliable-ordered control messages, while attaching large blocks of data (larger than max packet size), while having all messages delivered reliably and in-order. 
-        Situations where this can be useful is when sending down the initial state of the world on client connect, or block of configuration data to send up from the client to server on connect.
-        It can also be used for messages sent across an unreliable-unordered channel, but in that case blocks aren't split up into fragments. Make sure you consider this when designing your channel budgets when sending blocks over unreliable-unordered channels.
         @see ChannelConfig
      */
 
@@ -3728,10 +3733,13 @@ namespace yojimbo
 
     /**
         Defines the set of message types that can be created.
+
         You can derive a message factory yourself to create your own message types, or you can use these helper macros to do it for you:
+        
             YOJIMBO_MESSAGE_FACTORY_START
             YOJIMBO_DECLARE_MESSAGE_TYPE
             YOJIMBO_MESSAGE_FACTORY_FINISH
+        
         See tests/shared.h for an example showing how to use the macros.
      */
 
@@ -4614,7 +4622,7 @@ namespace yojimbo
     };
 
     /**
-        Connection class.
+        Sends and receives messages across a set of user defined channels.
      */
 
     class Connection
@@ -4818,9 +4826,9 @@ namespace yojimbo
     };
 
     /** 
-        Adapter class
-        This is used to integrate your game engine with yojimbo. 
-        It lets you specify the message factory to be used by client and server, as well as to implement various callbacks.
+        Specifies the message factory and callbacks for clients and servers.
+        An instance of this class is passed into the client and server constructors. 
+        You can share the same adapter across a client/server pair if you have local multiplayer, eg. loopback.
      */
 
     class Adapter
@@ -4829,20 +4837,42 @@ namespace yojimbo
 
         virtual ~Adapter() {}
 
-        // todo: document this class
+        /**
+            Override this function to specify your own custom allocator class.
+            @param allocator The base allocator that must be used to allocate your allocator instance.
+            @param memory The block of memory backing your allocator.
+            @param bytes The number of bytes of memory available to your allocator.
+            @returns A pointer to the allocator instance you created.
+         */
 
         virtual Allocator * CreateAllocator( Allocator & allocator, void * memory, size_t bytes )
         {
             return YOJIMBO_NEW( allocator, TLSF_Allocator, memory, bytes );
         }
 
+        /**
+            You must override this method to create the message factory used by the client and server.
+            @param allocator The allocator that must be used to create your message factory instance via YOJIMBO_NEW
+            @returns The message factory pointer you created.
+
+         */
+
         virtual MessageFactory * CreateMessageFactory( Allocator & allocator )
         {
             (void) allocator;
             yojimbo_assert( false );
             return NULL;
         }
 
+        /** 
+            Override this callback to process packets sent from client to server over loopback.
+            @param clientIndex The client index in range [0,maxClients-1]
+            @param packetData The packet data (raw) to be sent to the server.
+            @param packetBytes The number of packet bytes in the server.
+            @param packetSequence The sequence number of the packet.
+            @see Client::ConnectLoopback
+         */
+
         virtual void ClientSendLoopbackPacket( int clientIndex, const uint8_t * packetData, int packetBytes, uint64_t packetSequence )
         {
             (void) clientIndex;
@@ -4852,6 +4882,15 @@ namespace yojimbo
             yojimbo_assert( false );
         }
 
+        /**
+            Override this callback to process packets sent from client to server over loopback.
+            @param clientIndex The client index in range [0,maxClients-1]
+            @param packetData The packet data (raw) to be sent to the server.
+            @param packetBytes The number of packet bytes in the server.
+            @param packetSequence The sequence number of the packet.
+            @see Server::ConnectLoopbackClient
+         */
+
         virtual void ServerSendLoopbackPacket( int clientIndex, const uint8_t * packetData, int packetBytes, uint64_t packetSequence )
         {
             (void) clientIndex;
@@ -4863,7 +4902,8 @@ namespace yojimbo
     };
 
     /**
-        Network Info
+        Network information for a client connection.
+        Contains statistics like round trip time (RTT), packet loss %, number of packets sent, received and acked.
      */
 
     struct NetworkInfo
@@ -4876,7 +4916,7 @@ namespace yojimbo
     };
 
     /**
-        Server interface
+        The server interface.
      */
 
     class ServerInterface
@@ -5210,7 +5250,7 @@ namespace yojimbo
     };
 
     /**
-        Server implementation.
+        Dedicated server implementation.
      */
 
     class Server : public BaseServer
@@ -5280,7 +5320,7 @@ namespace yojimbo
     };
 
     /** 
-        Client interface.
+        The common interface for all clients.
      */
 
     class ClientInterface
@@ -5492,7 +5532,7 @@ namespace yojimbo
     };
 
     /**
-        Functionality shared across all client implementations.
+        Functionality that is common across all client implementations.
      */
 
     class BaseClient : public ClientInterface
@@ -5618,7 +5658,7 @@ namespace yojimbo
     };
 
     /**
-        Client implementation.
+        Implementation of client for dedicated servers.
      */
 
     class Client : public BaseClient