proto: Add missing docs for WriteRef RPC

3 files changed, 21 insertions, 15 deletions

diff --git a/proto/go/gitalypb/repository.pb.go b/proto/go/gitalypb/repository.pb.go
index 4453d5a0a..ee57a490e 100644
--- a/proto/go/gitalypb/repository.pb.go
+++ b/proto/go/gitalypb/repository.pb.go
@@ -1713,19 +1713,22 @@ func (x *FsckResponse) GetError() []byte {
 	return nil
 }
 
-// WriteRefRequest ...
+// WriteRefRequest is a request for the WriteRef RPC.
 type WriteRefRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository ...
+	// repository is the repo in which to write a ref. The storage_name and relative_path
+	// attributes must be provided.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// ref ...
+	// ref is the ref to create or update. It should be a fully-resolved value like refs/heads/main.
 	Ref []byte `protobuf:"bytes,2,opt,name=ref,proto3" json:"ref,omitempty"`
-	// revision ...
+	// revision is the new value that the ref should point to.
 	Revision []byte `protobuf:"bytes,3,opt,name=revision,proto3" json:"revision,omitempty"`
-	// old_revision ...
+	// old_revision is the previous value of the ref, used to prevent race conditions.
+	// If an all-zero object ID is provided, the ref will only be updated if it did not
+	// previously exist.
 	OldRevision []byte `protobuf:"bytes,4,opt,name=old_revision,json=oldRevision,proto3" json:"old_revision,omitempty"`
 	// force ...
 	Force bool `protobuf:"varint,5,opt,name=force,proto3" json:"force,omitempty"`
@@ -1798,7 +1801,7 @@ func (x *WriteRefRequest) GetForce() bool {
 	return false
 }
 
-// WriteRefResponse ...
+// WriteRefResponse is a response for the WriteRef RPC.
 type WriteRefResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
diff --git a/proto/go/gitalypb/repository_grpc.pb.go b/proto/go/gitalypb/repository_grpc.pb.go
index b61272442..8343142c1 100644
--- a/proto/go/gitalypb/repository_grpc.pb.go
+++ b/proto/go/gitalypb/repository_grpc.pb.go
@@ -74,7 +74,7 @@ type RepositoryServiceClient interface {
 	// Fsck checks the repository for consistency via git-fsck(1). This can be used to check for
 	// repository corruption.
 	Fsck(ctx context.Context, in *FsckRequest, opts ...grpc.CallOption) (*FsckResponse, error)
-	// WriteRef ...
+	// WriteRef creates or updates a ref in a repository to point to a new value.
 	WriteRef(ctx context.Context, in *WriteRefRequest, opts ...grpc.CallOption) (*WriteRefResponse, error)
 	// FindMergeBase ...
 	FindMergeBase(ctx context.Context, in *FindMergeBaseRequest, opts ...grpc.CallOption) (*FindMergeBaseResponse, error)
@@ -1041,7 +1041,7 @@ type RepositoryServiceServer interface {
 	// Fsck checks the repository for consistency via git-fsck(1). This can be used to check for
 	// repository corruption.
 	Fsck(context.Context, *FsckRequest) (*FsckResponse, error)
-	// WriteRef ...
+	// WriteRef creates or updates a ref in a repository to point to a new value.
 	WriteRef(context.Context, *WriteRefRequest) (*WriteRefResponse, error)
 	// FindMergeBase ...
 	FindMergeBase(context.Context, *FindMergeBaseRequest) (*FindMergeBaseResponse, error)
diff --git a/proto/repository.proto b/proto/repository.proto
index f02890e67..653343301 100644
--- a/proto/repository.proto
+++ b/proto/repository.proto
@@ -122,7 +122,7 @@ service RepositoryService {
     };
   }
 
-  // WriteRef ...
+  // WriteRef creates or updates a ref in a repository to point to a new value.
   rpc WriteRef(WriteRefRequest) returns (WriteRefResponse) {
     option (op_type) = {
       op: MUTATOR
@@ -704,15 +704,18 @@ message FsckResponse {
   bytes error = 1;
 }
 
-// WriteRefRequest ...
+// WriteRefRequest is a request for the WriteRef RPC.
 message WriteRefRequest {
-  // repository ...
+  // repository is the repo in which to write a ref. The storage_name and relative_path
+  // attributes must be provided.
   Repository repository = 1 [(target_repository)=true];
-  // ref ...
+  // ref is the ref to create or update. It should be a fully-resolved value like refs/heads/main.
   bytes ref = 2;
-  // revision ...
+  // revision is the new value that the ref should point to.
   bytes revision = 3;
-  // old_revision ...
+  // old_revision is the previous value of the ref, used to prevent race conditions.
+  // If an all-zero object ID is provided, the ref will only be updated if it did not
+  // previously exist.
   bytes old_revision = 4;
   // force ...
   bool force = 5;
@@ -721,7 +724,7 @@ message WriteRefRequest {
   reserved 6;
 }
 
-// WriteRefResponse ...
+// WriteRefResponse is a response for the WriteRef RPC.
 message WriteRefResponse {
   // This used to contain an error message. Since we're shelling out
   // all exceptions are wrapped in GRPC errors.