proto: Add documentation for `RemoteService`

Some of the RPC definitions and protobuf message types in the
`RemoteService` lack documentation. Add the missing documentation.

3 files changed, 27 insertions, 21 deletions

diff --git a/proto/go/gitalypb/remote.pb.go b/proto/go/gitalypb/remote.pb.go
index 89b59a3b6..612b4d5cb 100644
--- a/proto/go/gitalypb/remote.pb.go
+++ b/proto/go/gitalypb/remote.pb.go
@@ -20,7 +20,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
-// UpdateRemoteMirrorRequest ...
+// UpdateRemoteMirrorRequest is a request for the UpdateRemoteMirror RPC.
 type UpdateRemoteMirrorRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
@@ -124,7 +124,7 @@ func (x *UpdateRemoteMirrorRequest) GetKeepDivergentRefs() bool {
 	return false
 }
 
-// UpdateRemoteMirrorResponse ...
+// UpdateRemoteMirrorResponse is a response for the UpdateRemoteMirror RPC.
 type UpdateRemoteMirrorResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
@@ -174,13 +174,14 @@ func (x *UpdateRemoteMirrorResponse) GetDivergentRefs() [][]byte {
 	return nil
 }
 
-// FindRemoteRepositoryRequest ...
+// FindRemoteRepositoryRequest is a request for the FindRemoteRepository RPC.
 type FindRemoteRepositoryRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// remote ...
+	// remote is the remote repository being checked. Because this RPC is not executed within a
+	// repository, the remote parameter must specify a valid Git URL for the targeted repository.
 	Remote string `protobuf:"bytes,1,opt,name=remote,proto3" json:"remote,omitempty"`
 	// storage_name is used to redirect request to proper storage where it can be handled.
 	// As of now it doesn't matter what storage will be used, but it still must be a valid.
@@ -234,15 +235,14 @@ func (x *FindRemoteRepositoryRequest) GetStorageName() string {
 	return ""
 }
 
-// FindRemoteRepositoryResponse ...
-// This migth throw a GRPC Unavailable code, to signal the request failure
-// is transient.
+// FindRemoteRepositoryResponse is a response for the FindRemoteRepository RPC. This might throw a
+// GRPC Unavailable code to signal the request failure is transient.
 type FindRemoteRepositoryResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// exists ...
+	// exists specifies if the remote repository exists.
 	Exists bool `protobuf:"varint,1,opt,name=exists,proto3" json:"exists,omitempty"`
 }
 
@@ -419,7 +419,7 @@ func (x *FindRemoteRootRefResponse) GetRef() string {
 	return ""
 }
 
-// Remote ...
+// Remote defines a remote repository that diverged references should be pushed to.
 type UpdateRemoteMirrorRequest_Remote struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
diff --git a/proto/go/gitalypb/remote_grpc.pb.go b/proto/go/gitalypb/remote_grpc.pb.go
index 070a9bf0c..4d8153490 100644
--- a/proto/go/gitalypb/remote_grpc.pb.go
+++ b/proto/go/gitalypb/remote_grpc.pb.go
@@ -28,7 +28,9 @@ type RemoteServiceClient interface {
 	// deleted from the mirror. UpdateRemoteMirror updates all tags. Branches are updated if they match
 	// the patterns specified in the requests.
 	UpdateRemoteMirror(ctx context.Context, opts ...grpc.CallOption) (RemoteService_UpdateRemoteMirrorClient, error)
-	// FindRemoteRepository ...
+	// FindRemoteRepository detects whether a repository exists at the given URI. This is done by
+	// asking git-ls-remote(1) to enumerate the remote's HEAD and then checking that we recognize it
+	// as a valid reference.
 	FindRemoteRepository(ctx context.Context, in *FindRemoteRepositoryRequest, opts ...grpc.CallOption) (*FindRemoteRepositoryResponse, error)
 	// FindRemoteRootRef tries to find the root reference of a remote
 	// repository. The root reference is the default branch as pointed to by
@@ -108,7 +110,9 @@ type RemoteServiceServer interface {
 	// deleted from the mirror. UpdateRemoteMirror updates all tags. Branches are updated if they match
 	// the patterns specified in the requests.
 	UpdateRemoteMirror(RemoteService_UpdateRemoteMirrorServer) error
-	// FindRemoteRepository ...
+	// FindRemoteRepository detects whether a repository exists at the given URI. This is done by
+	// asking git-ls-remote(1) to enumerate the remote's HEAD and then checking that we recognize it
+	// as a valid reference.
 	FindRemoteRepository(context.Context, *FindRemoteRepositoryRequest) (*FindRemoteRepositoryResponse, error)
 	// FindRemoteRootRef tries to find the root reference of a remote
 	// repository. The root reference is the default branch as pointed to by
diff --git a/proto/remote.proto b/proto/remote.proto
index 00d989fbb..110d7f058 100644
--- a/proto/remote.proto
+++ b/proto/remote.proto
@@ -22,7 +22,9 @@ service RemoteService {
       };
   }
 
-  // FindRemoteRepository ...
+  // FindRemoteRepository detects whether a repository exists at the given URI. This is done by
+  // asking git-ls-remote(1) to enumerate the remote's HEAD and then checking that we recognize it
+  // as a valid reference.
   rpc FindRemoteRepository(FindRemoteRepositoryRequest) returns (FindRemoteRepositoryResponse) {
     option (op_type) = {
         op: ACCESSOR
@@ -42,9 +44,9 @@ service RemoteService {
   }
 }
 
-// UpdateRemoteMirrorRequest ...
+// UpdateRemoteMirrorRequest is a request for the UpdateRemoteMirror RPC.
 message UpdateRemoteMirrorRequest {
-  // Remote ...
+  // Remote defines a remote repository that diverged references should be pushed to.
   message Remote {
     // url is the URL of the remote repository.
     string url = 1;
@@ -91,16 +93,17 @@ message UpdateRemoteMirrorRequest {
   reserved "ref_name";
 }
 
-// UpdateRemoteMirrorResponse ...
+// UpdateRemoteMirrorResponse is a response for the UpdateRemoteMirror RPC.
 message UpdateRemoteMirrorResponse {
   // divergent_refs contains a list of references that had diverged in the
   // mirror from the source repository.
   repeated bytes divergent_refs = 1;
 }
 
-// FindRemoteRepositoryRequest ...
+// FindRemoteRepositoryRequest is a request for the FindRemoteRepository RPC.
 message FindRemoteRepositoryRequest {
-  // remote ...
+  // remote is the remote repository being checked. Because this RPC is not executed within a
+  // repository, the remote parameter must specify a valid Git URL for the targeted repository.
   string remote = 1;
   // storage_name is used to redirect request to proper storage where it can be handled.
   // As of now it doesn't matter what storage will be used, but it still must be a valid.
@@ -108,11 +111,10 @@ message FindRemoteRepositoryRequest {
   string storage_name = 2 [(storage)=true];
 }
 
-// FindRemoteRepositoryResponse ...
-// This migth throw a GRPC Unavailable code, to signal the request failure
-// is transient.
+// FindRemoteRepositoryResponse is a response for the FindRemoteRepository RPC. This might throw a
+// GRPC Unavailable code to signal the request failure is transient.
 message FindRemoteRepositoryResponse {
-  // exists ...
+  // exists specifies if the remote repository exists.
   bool exists = 1;
 }