[Networking] Doxygen

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
 }