proto: Add documentation to `smarthttp.proto`

The `smarthttp.proto` protobuf is missing documentation. Let's amend
the existing documentation and add missing documenatation.

Closes https://gitlab.com/gitlab-org/gitaly/-/issues/5120

1 files changed, 49 insertions, 32 deletions

diff --git a/proto/smarthttp.proto b/proto/smarthttp.proto
index d54d123e5..3094bfb23 100644
--- a/proto/smarthttp.proto
+++ b/proto/smarthttp.proto
@@ -10,32 +10,42 @@ option go_package = "gitlab.com/gitlab-org/gitaly/v16/proto/go/gitalypb";
 // SmartHTTPService is a service that provides RPCs required for HTTP-based Git
 // clones via the smart HTTP protocol.
 service SmartHTTPService {
-  // The response body for GET /info/refs?service=git-upload-pack
-  // Will be invoked when the user executes a `git fetch`, meaning the server
-  // will upload the packs to that user. The user doesn't upload new objects.
+  // InfoRefsUploadPack provides the response for GET /info/refs?service=git-upload-pack.
+  // It is invoked when the client fetches packs from the server, meaning the server will
+  // upload the packs to that client. The client doesn't upload new objects. This is used
+  // to advertise the references available on the server to the client via
+  // git-upload-pack(1)'s `--advertise-refs` option.
   rpc InfoRefsUploadPack(InfoRefsRequest) returns (stream InfoRefsResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // The response body for GET /info/refs?service=git-receive-pack
-  // Will be invoked when the user executes a `git push`, but only advertises
-  // references to the user.
+  // InfoRefsReceivePack provides the response for GET /info/refs?service=git-receive-pack.
+  // It is invoked when the client pushes packs to the server, meaning the server
+  // will fetch the packs from the client. This is used to advertise the references
+  // available on the server to the client via git-receive-pack(1)'s `--advertise-refs`
+  // option.
   rpc InfoRefsReceivePack(InfoRefsRequest) returns (stream InfoRefsResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // Request and response body for POST /upload-pack using sidechannel protocol
+
+  // PostUploadPackWithSidechannel provides the response for POST /upload-pack. It
+  // used to transfer pack files from the server to the client via sidechannels. This
+  // is invoked when the client executes `git fetch`.
+  //
+  // More info on sidechannels: https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/sidechannel.md
   rpc PostUploadPackWithSidechannel(PostUploadPackWithSidechannelRequest) returns (PostUploadPackWithSidechannelResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // Request and response body for POST /receive-pack
+  // PostReceivePack provides the response for POST /receive-pack. It used to transfer
+  // pack files from the client to the server. This is invoked when the client executes `git push`.
   rpc PostReceivePack(stream PostReceivePackRequest) returns (stream PostReceivePackResponse) {
     option (op_type) = {
       op: MUTATOR
@@ -43,59 +53,66 @@ service SmartHTTPService {
   }
 }
 
-// This comment is left unintentionally blank.
+// InfoRefsRequest is a request for the InfoRefsUploadPack and InfoRefsUploadPack rpcs.
 message InfoRefsRequest {
-  // This comment is left unintentionally blank.
+  // Repository is the repository on which to operate.
   Repository repository = 1 [(target_repository)=true];
-  // Parameters to use with git -c (key=value pairs)
+  // GitConfigOptions are parameters to use with git -c (key=value pairs).
   repeated string git_config_options = 2;
-
-  // Git protocol version
+  // GitProtocol is the git protocol version.
   string git_protocol = 3;
 }
 
-// This comment is left unintentionally blank.
+// InfoRefsResponse is the response of InfoRefsUploadPack and InfoRefsUploadPack rpcs.
+// It is used to provide the client with the servers advertised refs.
 message InfoRefsResponse {
-  // This comment is left unintentionally blank.
+  // Data is the raw data copied from the stdout of git-upload-pack(1) or
+  // git-receive-pack(1) when used with the `--advertise-refs` flag.
   bytes data = 1;
 }
 
-// This comment is left unintentionally blank.
+// PostUploadPackWithSidechannelRequest is the request for the PostUploadPackWithSidechannel rpc.
 message PostUploadPackWithSidechannelRequest {
-  // repository should only be present in the first message of the stream
+  // Repository is the repository on which to operate.
   Repository repository = 1 [(target_repository)=true];
-  // Parameters to use with git -c (key=value pairs)
+  // GitConfigOptions are parameters to use with git -c (key=value pairs).
   repeated string git_config_options = 2;
-  // Git protocol version
+  // GitProtocol is the git protocol version.
   string git_protocol = 3;
 }
 
-// This comment is left unintentionally blank.
+// PostUploadPackWithSidechannelResponse is the response for the PostUploadPackWithSidechannel rpc.
+// This is an empty response since the raw data is transferred to the client via the sidechannel
+// exclusively.
 message PostUploadPackWithSidechannelResponse {
 }
 
-// This comment is left unintentionally blank.
+// PostReceivePackRequest is the request for the PostReceivePack rpc. It is a stream used to
+// transfer the raw data from the client to the servers stdin of git-receive-pack(1) process.
 message PostReceivePackRequest {
-  // repository should only be present in the first message of the stream
+  // Repository is the repository on which to operate.
+  // It should only be present in the first message of the stream.
   Repository repository = 1 [(target_repository)=true];
-  // Raw data to be copied to stdin of 'git receive-pack'
+  // Data is the raw data to be copied to stdin of 'git receive-pack'.
   bytes data = 2;
-  // gl_id, gl_repository, and gl_username become env variables, used by the Git {pre,post}-receive
-  // hooks. They should only be present in the first message of the stream.
+  // GlID is the GitLab ID of the user. This is used by Git {pre,post}-receive hooks.
+  // It should only be present in the first message of the stream.
   string gl_id = 3;
-  // This comment is left unintentionally blank.
+  // GlRepository refers to the GitLab repository. This is used by Git {pre,post}-receive hooks.
+  // It should only be present in the first message of the stream.
   string gl_repository = 4;
-  // This comment is left unintentionally blank.
+  // GlID is the GitLab Username of the user. This is used by Git {pre,post}-receive hooks.
+  // It should only be present in the first message of the stream.
   string gl_username = 5;
-  // Git protocol version
+  // GitProtocol is the git protocol version.
   string git_protocol = 6;
-
-  // Parameters to use with git -c (key=value pairs)
+  // GitConfigOptions are parameters to use with git -c (key=value pairs).
   repeated string git_config_options = 7;
 }
 
-// This comment is left unintentionally blank.
+// PostReceivePackResponse is the response for the PostReceivePack rpc. It is a stream used to
+// transfer the raw data from the stdout of git-receive-pack(1) from the server to the client.
 message PostReceivePackResponse {
-  // Raw data from stdout of 'git receive-pack'
+  // Data is the raw data from the stdout of 'git receive-pack'.
   bytes data = 1;
 }