Clean, format and comment the rove.proto file

proto/rove/rove.proto

@@ -2,38 +2,91 @@ syntax = "proto3";
 
 // Rove
 //
-// Rove is an asychronous nomadic game about exploring a planet as part of a loose community
+// Rove is an asychronous nomadic game about exploring a planet as part of a
+// loose community
 package rove;
-
 option go_package = "github.com/mdiluz/rove/pkg/rove";
 
+// The Rove server hosts a single game session and world with multiple players
 service Rove {
   // Server status
-    // 
   // Responds with various details about the current server status
   rpc ServerStatus(ServerStatusRequest) returns (ServerStatusResponse) {}
 
   // Register an account
-    // 
   // Tries to register an account with the given name
   rpc Register(RegisterRequest) returns (RegisterResponse) {}
 
   // Send commands to rover
-    // 
+  // Sending commands to this endpoint will queue them to be executed during the
-    // Sending commands to this endpoint will queue them to be executed during the following ticks, in the order sent
+  // following ticks, in the order sent. Commands sent within the same tick will
+  // overwrite until the tick has finished and the commands are queued
   rpc Command(CommandRequest) returns (CommandResponse) {}
 
   // Get radar information
-    // 
   // Gets the radar output for the given rover
   rpc Radar(RadarRequest) returns (RadarResponse) {}
 
   // Get rover information
-    // 
   // Gets information for the account's rover
   rpc Status(StatusRequest) returns (StatusResponse) {}
 }
 
+//
+// ServerStatus
+//
+
+// ServerStatusRequest is an empty placeholder
+message ServerStatusRequest {}
+
+// ServerStatusResponse is a response with useful server information
+message ServerStatusResponse {
+  // The version of the server in v{major}.{minor}-{delta}-{sha} form
+  string version = 1;
+
+  // Whether the server is ready to accept requests
+  bool ready = 2;
+
+  // The tick rate of the server in minutes (how many minutes per tick)
+  int32 tickRate = 3;
+
+  // The current tick of the server
+  int32 currentTick = 4;
+
+  // The time the next tick will occur
+  string next_tick = 5;
+}
+
+//
+// Register
+//
+
+// RegisterRequest contains data to register an account
+message RegisterRequest {
+  // The desired account name
+  string name = 1;
+}
+
+// Account describes a registered account
+message Account {
+  // The account name
+  string name = 1;
+
+  // The account secret value, given when creating the account
+  string secret = 2;
+}
+
+// RegisterResponse is the response given to registering an account
+message RegisterResponse {
+  // The registered account information
+  Account account = 1;
+}
+
+//
+// Command
+//
+
+// CommandType defines the type of a command to give to the rover
 enum CommandType {
   none = 0;
   // Move the rover in a direction, requires bearing
@@ -48,6 +101,7 @@ enum CommandType {
   broadcast = 5;
 }
 
+// Command is a single command for a rover
 message Command {
   // The command type
   CommandType command = 1;
@@ -64,6 +118,7 @@ message Command {
   }
 }
 
+// CommandRequest describes a set of commands to be requested for the rover
 message CommandRequest {
   // The account to execute these commands
   Account account = 1;
@@ -72,46 +127,43 @@ message CommandRequest {
   repeated Command commands = 2;
 }
 
-// Empty placeholder
+// CommandResponse is an empty placeholder
 message CommandResponse {}
 
-message Error {
+//
-    // An explanation for the HTTP error returned
+// Radar
-    string error = 1;
+//
-}
 
+// RadarRequest is the data needed to request the radar for a rover
 message RadarRequest {
   // The account for this request
   Account account = 1;
 }
 
+// RadarResponse describes radar information
 message RadarResponse {
   // The range in tiles from the rover of the radar data
   int32 range = 1;
 
-    // A 1D array representing range*2 + 1 squared set of tiles, origin bottom left and in row->column order
+  // A 1D array representing range*2 + 1 squared set of tiles, origin bottom
+  // left and in row->column order
   bytes tiles = 2;
 
   // A similar array to the tile array, but containing objects
   bytes objects = 3;
 }
 
-message RegisterRequest {
+//
-    // The desired account name
+// Status
-    string name = 1;
+//
-}
-
-// Empty placeholder
-message RegisterResponse{
-    // The registered account information
-    Account account = 1;
-}
 
+// StatusRequest is information needed to request rover status
 message StatusRequest {
   // The account for this request
   Account account = 1;
 }
 
+// Log is a single log item
 message Log {
   // The unix timestamp of the log
   string time = 1;
@@ -120,6 +172,13 @@ message Log {
   string text = 2;
 }
 
+// Vector describes a point or vector in 2D space
+message Vector {
+  int32 x = 1;
+  int32 y = 2;
+}
+
+// StatusResponse is the response given to a status request
 message StatusResponse {
   // The name of the rover
   string name = 1;
@@ -157,33 +216,3 @@ message StatusResponse {
   // The most recent logs
   repeated Log logs = 12;
 }
-
-// Empty placeholder
-message ServerStatusRequest {}
-
-message ServerStatusResponse {
-    // The version of the server in v{major}.{minor}-{delta}-{sha} form
-    string version = 1;
-
-    // Whether the server is ready to accept requests
-    bool ready = 2;
-
-    // The tick rate of the server in minutes (how many minutes per tick)
-    int32 tickRate = 3;
-
-    // The current tick of the server
-    int32 currentTick = 4;
-
-    // The time the next tick will occur
-    string next_tick = 5;
-}
-
-message Vector {
-    int32 x = 1;
-    int32 y = 2;
-}
-
-message Account {
-    string name = 1;
-    string secret = 2;
-}