[Networking] Doxygen

libcockatrice_protocol/libcockatrice/protocol/pb/game_commands.proto

@@ -1,56 +1,197 @@
 syntax = "proto2";
 
-// Commands that are sent during a game to change the game state
+/// Commands that are sent during a game to change the game state
 message GameCommand {
+
+    /// Identifies the concrete game command to execute
     enum GameCommandType {
+
+        /// Kick a player from the game.
+        /// Server: Server_Game::handleKickFromGame
+        /// Client: reflected via game state events
         KICK_FROM_GAME = 1000;
+
+        /// Leave the current game voluntarily.
+        /// Server: Server_Game::handleLeaveGame
+        /// Client: reflected via game state events
         LEAVE_GAME = 1001;
+
+        /// Send an in-game chat message.
+        /// Server: Server_Game::handleGameSay
+        /// Client: PlayerEventHandler::eventGameSay
         GAME_SAY = 1002;
+
+        /// Shuffle a zone (typically the library).
+        /// Server: Server_Game::handleShuffle
+        /// Client: PlayerEventHandler::eventShuffle
         SHUFFLE = 1003;
+
+        /// Take a mulligan at game start.
+        /// Server: Server_Game::handleMulligan
+        /// Client: reflected via game state events
         MULLIGAN = 1004;
+
+        /// Roll one or more dice.
+        /// Server: Server_Game::handleRollDie
+        /// Client: PlayerEventHandler::eventRollDie
         ROLL_DIE = 1005;
+
+        /// Draw cards from the deck.
+        /// Server: Server_Game::handleDrawCards
+        /// Client: PlayerEventHandler::eventDrawCards
         DRAW_CARDS = 1006;
+
+        /// Undo a previous draw action.
+        /// Server: Server_Game::handleUndoDraw
+        /// Client: PlayerEventHandler::eventMoveCard (Context_UndoDraw)
         UNDO_DRAW = 1007;
+
+        /// Flip a card face up or face down.
+        /// Server: Server_Game::handleFlipCard
+        /// Client: PlayerEventHandler::eventFlipCard
         FLIP_CARD = 1008;
+
+        /// Attach one card to another.
+        /// Server: Server_Game::handleAttachCard
+        /// Client: PlayerEventHandler::eventAttachCard
         ATTACH_CARD = 1009;
+
+        /// Create a token card.
+        /// Server: Server_Game::handleCreateToken
+        /// Client: PlayerEventHandler::eventCreateToken
         CREATE_TOKEN = 1010;
+
+        /// Create a visual arrow between objects.
+        /// Server: Server_Game::handleCreateArrow
+        /// Client: PlayerEventHandler::eventCreateArrow
         CREATE_ARROW = 1011;
+
+        /// Delete a visual arrow.
+        /// Server: Server_Game::handleDeleteArrow
+        /// Client: PlayerEventHandler::eventDeleteArrow
         DELETE_ARROW = 1012;
+
+        /// Set a card attribute (e.g. tapped, flipped).
+        /// Server: Server_Game::handleSetCardAttr
+        /// Client: PlayerEventHandler::eventSetCardAttr
         SET_CARD_ATTR = 1013;
+
+        /// Set a counter value on a card.
+        /// Server: Server_Game::handleSetCardCounter
+        /// Client: PlayerEventHandler::eventSetCardCounter
         SET_CARD_COUNTER = 1014;
+
+        /// Increment a counter on a card.
+        /// Server: Server_Game::handleIncCardCounter
+        /// Client: PlayerEventHandler::eventSetCardCounter
         INC_CARD_COUNTER = 1015;
+
+        /// Mark the player as ready to start the game.
+        /// Server: Server_Game::handleReadyStart
+        /// Client: reflected via game state events
         READY_START = 1016;
+
+        /// Concede the game.
+        /// Server: Server_Game::handleConcede
+        /// Client: reflected via game state events
         CONCEDE = 1017;
+
+        /// Increment a global (non-card) counter.
+        /// Server: Server_Game::handleIncCounter
+        /// Client: PlayerEventHandler::eventSetCounter
         INC_COUNTER = 1018;
+
+        /// Create a new global counter.
+        /// Server: Server_Game::handleCreateCounter
+        /// Client: PlayerEventHandler::eventCreateCounter
         CREATE_COUNTER = 1019;
+
+        /// Set a global counter value.
+        /// Server: Server_Game::handleSetCounter
+        /// Client: PlayerEventHandler::eventSetCounter
         SET_COUNTER = 1020;
+
+        /// Delete a global counter.
+        /// Server: Server_Game::handleDelCounter
+        /// Client: PlayerEventHandler::eventDelCounter
         DEL_COUNTER = 1021;
+
+        /// Advance to the next turn.
+        /// Server: Server_Game::handleNextTurn
+        /// Client: reflected via active player / phase events
         NEXT_TURN = 1022;
+
+        /// Set the active phase of the turn.
+        /// Server: Server_Game::handleSetActivePhase
+        /// Client: reflected via game state events
         SET_ACTIVE_PHASE = 1023;
+
+        /// Dump the contents of a zone.
+        /// Server: Server_Game::handleDumpZone
+        /// Client: PlayerEventHandler::eventDumpZone
         DUMP_ZONE = 1024;
-        // STOP_DUMP_ZONE = 1025; // obsolete
+
+        /// Reveal specific cards to players.
+        /// Server: Server_Game::handleRevealCards
+        /// Client: PlayerEventHandler::eventRevealCards
         REVEAL_CARDS = 1026;
+
+        /// Move a card between zones.
+        /// Server: Server_Game::handleMoveCard
+        /// Client: PlayerEventHandler::eventMoveCard
         MOVE_CARD = 1027;
+
+        /// Set the sideboard plan for the game.
+        /// Server: Server_Game::handleSetSideboardPlan
+        /// Client: not forwarded as a game event
         SET_SIDEBOARD_PLAN = 1028;
+
+        /// Select a deck for the game.
+        /// Server: Server_Game::handleDeckSelect
+        /// Client: reflected via lobby / game state
         DECK_SELECT = 1029;
+
+        /// Lock or unlock sideboarding.
+        /// Server: Server_Game::handleSetSideboardLock
+        /// Client: reflected via game state
         SET_SIDEBOARD_LOCK = 1030;
+
+        /// Change zone properties (visibility, reveal-top, etc.).
+        /// Server: Server_Game::handleChangeZoneProperties
+        /// Client: PlayerEventHandler::eventChangeZoneProperties
         CHANGE_ZONE_PROPERTIES = 1031;
+
+        /// Undo a previous concede.
+        /// Server: Server_Game::handleUnconcede
+        /// Client: reflected via game state
         UNCONCEDE = 1032;
+
+        /// Execute a command on behalf of another player.
+        /// Server: Server_Game::handleJudge
+        /// Client: transparent (wrapped commands handled normally)
         JUDGE = 1033;
+
+        /// Reverse the current turn order.
+        /// Server: Server_Game::handleReverseTurn
+        /// Client: reflected via subsequent turn events
         REVERSE_TURN = 1034;
     }
+
     extensions 100 to max;
 }
 
-// A wrapper around a normal game command that allows a privileged user to send a command on behalf of another player
+/// A wrapper around a normal game command that allows a privileged user
+/// to send a command on behalf of another player.
 message Command_Judge {
+
     extend GameCommand {
+        /// Judge command extension payload
         optional Command_Judge ext = 1033;
     }
 
-    // The player on whose behalf this command is sent
+    /// The player on whose behalf this command is sent.
     optional sint32 target_id = 1 [default = -1];
 
-    // The wrapped game command
+    /// One or more wrapped game commands to execute.
     repeated GameCommand game_command = 2;
 }

libcockatrice_protocol/libcockatrice/protocol/pb/response.proto

@@ -1,35 +1,44 @@
 syntax = "proto2";
 
-// Sent immediately after a command with the same cmd_id, connecting it to the command sent to the server
+/// Server response envelope linking to a command
+/**
+ * This message is sent immediately after a client command, using the same `cmd_id`
+ * to connect the response to the command.
+ *
+ * Responses may contain standard outcome codes (`ResponseCode`) and indicate
+ * what type of response the server is sending (`ResponseType`).
+ */
 message Response {
+
+    // Outcome of the command sent by the client
     enum ResponseCode {
-        RespNotConnected = -1;
-        RespNothing = 0;
-        RespOk = 1;
-        RespNotInRoom = 2;
-        RespInternalError = 3;
-        RespInvalidCommand = 4;
-        RespInvalidData = 5;
-        RespNameNotFound = 6;
-        RespLoginNeeded = 7;
-        RespFunctionNotAllowed = 8;
-        RespGameNotStarted = 9;
-        RespGameFull = 10;
-        RespContextError = 11;
-        RespWrongPassword = 12;
-        RespSpectatorsNotAllowed = 13;
-        RespOnlyBuddies = 14;
-        RespUserLevelTooLow = 15;
-        RespInIgnoreList = 16;
-        RespWouldOverwriteOldSession = 17;
-        RespChatFlood = 18;
-        RespUserIsBanned = 19;
-        RespAccessDenied = 20;
-        RespUsernameInvalid = 21;
-        RespRegistrationRequired = 22;
-        RespRegistrationAccepted = 23;    // Server agrees to process client's registration request
-        RespUserAlreadyExists = 24;       // Client attempted to register a name which is already registered
-        RespEmailRequiredToRegister = 25; // Server requires email to register accounts but client did not provide one
+        RespNotConnected = -1;             // Client is not connected or session expired
+        RespNothing = 0;                   // No response required
+        RespOk = 1;                        // Command succeeded
+        RespNotInRoom = 2;                 // Client is not in the room for this command
+        RespInternalError = 3;             // Server encountered an unexpected error
+        RespInvalidCommand = 4;            // Command was invalid or unrecognized
+        RespInvalidData = 5;               // Command data was invalid or malformed
+        RespNameNotFound = 6;              // Target user not found
+        RespLoginNeeded = 7;               // Client must log in first
+        RespFunctionNotAllowed = 8;        // Client tried to perform a restricted action
+        RespGameNotStarted = 9;            // Game has not started yet
+        RespGameFull = 10;                 // Game is full
+        RespContextError = 11;             // Context (room/game) mismatch
+        RespWrongPassword = 12;            // Password for this room or game is incorrect
+        RespSpectatorsNotAllowed = 13;     // Spectators are not allowed in this room/game
+        RespOnlyBuddies = 14;              // Only buddies can perform this action
+        RespUserLevelTooLow = 15;          // User’s permission level is insufficient
+        RespInIgnoreList = 16;             // Target user has ignored the client
+        RespWouldOverwriteOldSession = 17; // Would overwrite an existing session
+        RespChatFlood = 18;                // Too many messages sent in short time
+        RespUserIsBanned = 19;             // Client is banned
+        RespAccessDenied = 20;             // Access to this action is denied
+        RespUsernameInvalid = 21;          // Username is invalid
+        RespRegistrationRequired = 22;     // Registration is required
+        RespRegistrationAccepted = 23;     // Server agrees to process client's registration request
+        RespUserAlreadyExists = 24;        // Client attempted to register a name which is already registered
+        RespEmailRequiredToRegister = 25;  // Server requires email to register accounts but client did not provide one
         RespTooManyRequests = 26;  // Server refused to complete command because client has sent too many too quickly
         RespPasswordTooShort = 27; // Server requires a decent password
         RespAccountNotActivated =
@@ -45,33 +54,36 @@ message Response {
         RespServerFull = 36;           // Server user limit reached
         RespEmailBlackListed = 37;     // Server has blocked the email address provided for registration for some reason
     }
+
+    // Type of response, used to route handling on the client
     enum ResponseType {
-        JOIN_ROOM = 1000;
-        LIST_USERS = 1001;
-        GET_GAMES_OF_USER = 1002;
-        GET_USER_INFO = 1003;
-        DUMP_ZONE = 1004;
-        LOGIN = 1005;
-        DECK_LIST = 1006;
-        DECK_DOWNLOAD = 1007;
-        DECK_UPLOAD = 1008;
-        REGISTER = 1009;
-        ACTIVATE = 1010;
-        ADJUST_MOD = 1011;
-        BAN_HISTORY = 1012;
-        WARN_HISTORY = 1013;
-        WARN_LIST = 1014;
-        VIEW_LOG = 1015;
-        FORGOT_PASSWORD_REQUEST = 1016;
-        PASSWORD_SALT = 1017;
-        GET_ADMIN_NOTES = 1018;
-        REPLAY_LIST = 1100;
-        REPLAY_DOWNLOAD = 1101;
-        REPLAY_GET_CODE = 1102;
+        JOIN_ROOM = 1000;               // Response for joining a room
+        LIST_USERS = 1001;              // Response listing users
+        GET_GAMES_OF_USER = 1002;       // Response with user's games
+        GET_USER_INFO = 1003;           // Response with user info
+        DUMP_ZONE = 1004;               // Response with zone dump
+        LOGIN = 1005;                   // Response to login attempt
+        DECK_LIST = 1006;               // Response with deck list
+        DECK_DOWNLOAD = 1007;           // Response for deck download
+        DECK_UPLOAD = 1008;             // Response for deck upload
+        REGISTER = 1009;                // Response to registration
+        ACTIVATE = 1010;                // Response to activation
+        ADJUST_MOD = 1011;              // Response to mod adjustments
+        BAN_HISTORY = 1012;             // Response with ban history
+        WARN_HISTORY = 1013;            // Response with warn history
+        WARN_LIST = 1014;               // Response with current warnings
+        VIEW_LOG = 1015;                // Response with logs
+        FORGOT_PASSWORD_REQUEST = 1016; // Response to password reset request
+        PASSWORD_SALT = 1017;           // Response containing password salt
+        GET_ADMIN_NOTES = 1018;         // Response with admin notes
+        REPLAY_LIST = 1100;             // Response listing replays
+        REPLAY_DOWNLOAD = 1101;         // Response for replay download
+        REPLAY_GET_CODE = 1102;         // Response containing replay code
         CARD_ART_RULE_LIST = 1200;
     }
-    required uint64 cmd_id = 1;
-    optional ResponseCode response_code = 2;
 
-    extensions 100 to max;
+    required uint64 cmd_id = 1;              // Command ID that this response corresponds to
+    optional ResponseCode response_code = 2; // Outcome code of the command
+
+    extensions 100 to max; // Protobuf extensions reserved for future use
 }