Add some basic documentation to grpc protocol

Nothing too detailed, a basic outline.

--
PiperOrigin-RevId: 141205173
MOS_MIGRATED_REVID=141205173

src/main/protobuf/command_server.proto

@@ -13,55 +13,97 @@
 // limitations under the License.
 //
 // This file contains the protocol used to communicate between the Bazel client
-// and the server.
+// and the server. At a high level clients may call the CommandServer.run rpc
+// to initiates a Bazel command and CommandServer.cancel to cancel an in-flight
+// command. CommandServer.ping may be used to check for server liveness without
+// executing any commands. See documentation of individual messages for more
+// details.
 syntax = "proto3";
 
 package command_server;
 
 option java_package = "com.google.devtools.build.lib.server";
 option java_outer_classname = "CommandProtos";
 
+// Passed to CommandServer.run to initiate execution of a Bazel command.
 message RunRequest {
-  // This must be the request cookie from the output base. A rudimentary form of authentication.
+  // Request cookie from the output base of the server. This serves as a
+  // rudimentary form of mutual authentication.
   string cookie = 1;
+
+  // Command and command arguments. Does not include startup arguments.
   repeated bytes arg = 2;
-  bool block_for_lock = 3;  // If false, the client won't wait for another client to finish
+
+  // Tells the server whether or not the client is willing to wait for any
+  // concurrent in-flight request to complete (there are many commands which
+  // may not run concurrently). If false and there are in-flight requests then
+  // the server will return an error immediately.
+  bool block_for_lock = 3;
+
+  // A simple description of the client for reporting purposes. This value is
+  // required.
   string client_description = 4;
 }
 
+// Contains metadata and result data for a command execution.
 message RunResponse {
-  // The server always sets this to the response cookie from the output base. A rudimentary form
-  // of authentication.
+  // Request cookie from the output base of the server. This serves as a
+  // rudimentary form of mutual authentication. Set on every response.
   string cookie = 1;
+
+  // Standard out of the command, chunked. May be empty.
   bytes standard_output = 2;
+
+  // Standard error of the command, chunked. May be empty.
   bytes standard_error = 3;
-  bool finished = 4;    // Whether this is the last message of the stream
-  int32 exit_code = 5;  // Only valid for the last message in the stream
-  string command_id = 6;  // Randomly generated command identifier
+
+  // Whether this is the last message of the stream, signals that exit_code is
+  // valid.
+  bool finished = 4;
+
+  // The exit code of the command, only valid when finished is set.
+  int32 exit_code = 5;
+
+  // Randomly generated command identifier, this may be used to cancel execution
+  // of the command by issuing a cancel call. This should be sent to the client
+  // as soon as possible. This is not required to be set (non-empty) on every
+  // response.
+  string command_id = 6;
 }
 
+// Passed to CommandServer.cancel to initiate graceful cancellation of an
+// in-flight command.
 message CancelRequest {
+  // The client request cookie (see RunRequest.cookie).
   string cookie = 1;
+
+  // The id of the command to cancel.
   string command_id = 2;
 }
 
 message CancelResponse {
+  // The server response cookie (see RunResponse.cookie).
   string cookie = 1;
 }
 
+// Passed to CommandServer.ping to initiate a ping request.
 message PingRequest {
+  // The client request cookie (see RunRequest.cookie).
   string cookie = 1;
 }
 
 message PingResponse {
+  // The server response cookie (see RunResponse.cookie).
   string cookie = 1;
 }
 
 service CommandServer {
-  // Run a Bazel command.
+  // Run a Bazel command. See documentation of argument/return messages for
+  // details.
   rpc Run (RunRequest) returns (stream RunResponse) {}
 
-  // Cancel a currently running Bazel command
+  // Cancel a currently running Bazel command. May return before the run command
+  // actually terminates.
   rpc Cancel (CancelRequest) returns (CancelResponse) {}
 
   // Does not do anything. Used for liveness check.