proto: Document UserDeleteBranch RPC

The UserDeleteBranch RPC is missing documentation. Add it to document
its behaviour and expected error cases.

5 files changed, 60 insertions, 17 deletions

diff --git a/internal/gitaly/service/operations/branches.go b/internal/gitaly/service/operations/branches.go
index 8551ae9d7..a1bbb6d9c 100644
--- a/internal/gitaly/service/operations/branches.go
+++ b/internal/gitaly/service/operations/branches.go
@@ -143,7 +143,8 @@ func (s *Server) UserUpdateBranch(ctx context.Context, req *gitalypb.UserUpdateB
 	return &gitalypb.UserUpdateBranchResponse{}, nil
 }
 
-//nolint: revive,stylecheck // This is unintentionally missing documentation.
+// UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes
+// hooks and contacts Rails to verify that the user is indeed allowed to delete that branch.
 func (s *Server) UserDeleteBranch(ctx context.Context, req *gitalypb.UserDeleteBranchRequest) (*gitalypb.UserDeleteBranchResponse, error) {
 	// That we do the branch name & user check here first only in
 	// UserDelete but not UserCreate is "intentional", i.e. it's
diff --git a/proto/go/gitalypb/operations.pb.go b/proto/go/gitalypb/operations.pb.go
index 65d40126f..cf7423868 100644
--- a/proto/go/gitalypb/operations.pb.go
+++ b/proto/go/gitalypb/operations.pb.go
@@ -465,17 +465,21 @@ func (x *UserUpdateBranchResponse) GetPreReceiveError() string {
 	return ""
 }
 
-// This comment is left unintentionally blank.
+// UserDeleteBranchRequest is a request for the UserDeleteBranch RPC.
 type UserDeleteBranchRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// This comment is left unintentionally blank.
+	// Repository is the repository to delete the branch in.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// This comment is left unintentionally blank.
+	// BranchName is the name of the branch that shall be deleted. This is expected to be the branch
+	// name only, e.g. in case you want to delete `refs/heads/main` the request needs to only contain
+	// `main` as the branch name.
 	BranchName []byte `protobuf:"bytes,2,opt,name=branch_name,json=branchName,proto3" json:"branch_name,omitempty"`
-	// This comment is left unintentionally blank.
+	// User is the user on whose behalf we should delete the branch. This information is used to
+	// perform access checks against the Rails `/internal/allowed` API. This user is also exposed to
+	// any custom hooks executed as part of this RPC call.
 	User *User `protobuf:"bytes,3,opt,name=user,proto3" json:"user,omitempty"`
 }
 
@@ -532,13 +536,14 @@ func (x *UserDeleteBranchRequest) GetUser() *User {
 	return nil
 }
 
-// This comment is left unintentionally blank.
+// UserDeleteBranchResponse is a response for the UserDeleteBranch RPC.
 type UserDeleteBranchResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// This comment is left unintentionally blank.
+	// PreReceiveError is an error that is returned in case deletion of the branch failed either
+	// because of failing access checks or because hooks have refused the update.
 	PreReceiveError string `protobuf:"bytes,1,opt,name=pre_receive_error,json=preReceiveError,proto3" json:"pre_receive_error,omitempty"`
 }
 
diff --git a/proto/go/gitalypb/operations_grpc.pb.go b/proto/go/gitalypb/operations_grpc.pb.go
index a1db433bc..3ee7dabeb 100644
--- a/proto/go/gitalypb/operations_grpc.pb.go
+++ b/proto/go/gitalypb/operations_grpc.pb.go
@@ -22,7 +22,15 @@ type OperationServiceClient interface {
 	UserCreateBranch(ctx context.Context, in *UserCreateBranchRequest, opts ...grpc.CallOption) (*UserCreateBranchResponse, error)
 	// This comment is left unintentionally blank.
 	UserUpdateBranch(ctx context.Context, in *UserUpdateBranchRequest, opts ...grpc.CallOption) (*UserUpdateBranchResponse, error)
-	// This comment is left unintentionally blank.
+	// UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes
+	// hooks and contacts Rails to verify that the user is indeed allowed to delete that branch. The
+	// following known error conditions may happen:
+	//
+	// - Returns `InvalidArgument` in case either the branch name or user are not set.
+	// - Returns `FailedPrecondition` in case the branch does not exist.
+	// - Returns `OK` with a `PreReceiveError` in case custom hooks refused the update.
+	// - Returns `FailedPrecondition` in case updating the reference fails because of a concurrent
+	//   write to the same reference.
 	UserDeleteBranch(ctx context.Context, in *UserDeleteBranchRequest, opts ...grpc.CallOption) (*UserDeleteBranchResponse, error)
 	// UserCreateTag creates a new tag.
 	UserCreateTag(ctx context.Context, in *UserCreateTagRequest, opts ...grpc.CallOption) (*UserCreateTagResponse, error)
@@ -324,7 +332,15 @@ type OperationServiceServer interface {
 	UserCreateBranch(context.Context, *UserCreateBranchRequest) (*UserCreateBranchResponse, error)
 	// This comment is left unintentionally blank.
 	UserUpdateBranch(context.Context, *UserUpdateBranchRequest) (*UserUpdateBranchResponse, error)
-	// This comment is left unintentionally blank.
+	// UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes
+	// hooks and contacts Rails to verify that the user is indeed allowed to delete that branch. The
+	// following known error conditions may happen:
+	//
+	// - Returns `InvalidArgument` in case either the branch name or user are not set.
+	// - Returns `FailedPrecondition` in case the branch does not exist.
+	// - Returns `OK` with a `PreReceiveError` in case custom hooks refused the update.
+	// - Returns `FailedPrecondition` in case updating the reference fails because of a concurrent
+	//   write to the same reference.
 	UserDeleteBranch(context.Context, *UserDeleteBranchRequest) (*UserDeleteBranchResponse, error)
 	// UserCreateTag creates a new tag.
 	UserCreateTag(context.Context, *UserCreateTagRequest) (*UserCreateTagResponse, error)
diff --git a/proto/operations.proto b/proto/operations.proto
index c8ac89350..48d71f0e3 100644
--- a/proto/operations.proto
+++ b/proto/operations.proto
@@ -29,7 +29,15 @@ service OperationService {
     };
   }
 
-  // This comment is left unintentionally blank.
+  // UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes
+  // hooks and contacts Rails to verify that the user is indeed allowed to delete that branch. The
+  // following known error conditions may happen:
+  //
+  // - Returns `InvalidArgument` in case either the branch name or user are not set.
+  // - Returns `FailedPrecondition` in case the branch does not exist.
+  // - Returns `OK` with a `PreReceiveError` in case custom hooks refused the update.
+  // - Returns `FailedPrecondition` in case updating the reference fails because of a concurrent
+  //   write to the same reference.
   rpc UserDeleteBranch(UserDeleteBranchRequest) returns (UserDeleteBranchResponse) {
     option (op_type) = {
       op: MUTATOR
@@ -192,19 +200,24 @@ message UserUpdateBranchResponse {
   string pre_receive_error = 1;
 }
 
-// This comment is left unintentionally blank.
+// UserDeleteBranchRequest is a request for the UserDeleteBranch RPC.
 message UserDeleteBranchRequest {
-  // This comment is left unintentionally blank.
+  // Repository is the repository to delete the branch in.
   Repository repository = 1 [(target_repository)=true];
-  // This comment is left unintentionally blank.
+  // BranchName is the name of the branch that shall be deleted. This is expected to be the branch
+  // name only, e.g. in case you want to delete `refs/heads/main` the request needs to only contain
+  // `main` as the branch name.
   bytes branch_name = 2;
-  // This comment is left unintentionally blank.
+  // User is the user on whose behalf we should delete the branch. This information is used to
+  // perform access checks against the Rails `/internal/allowed` API. This user is also exposed to
+  // any custom hooks executed as part of this RPC call.
   User user = 3;
 }
 
-// This comment is left unintentionally blank.
+// UserDeleteBranchResponse is a response for the UserDeleteBranch RPC.
 message UserDeleteBranchResponse {
-  // This comment is left unintentionally blank.
+  // PreReceiveError is an error that is returned in case deletion of the branch failed either
+  // because of failing access checks or because hooks have refused the update.
   string pre_receive_error = 1;
 }
 
diff --git a/ruby/proto/gitaly/operations_services_pb.rb b/ruby/proto/gitaly/operations_services_pb.rb
index 05f1184f4..b71684ee1 100644
--- a/ruby/proto/gitaly/operations_services_pb.rb
+++ b/ruby/proto/gitaly/operations_services_pb.rb
@@ -22,7 +22,15 @@ module Gitaly
       rpc :UserCreateBranch, ::Gitaly::UserCreateBranchRequest, ::Gitaly::UserCreateBranchResponse
       # This comment is left unintentionally blank.
       rpc :UserUpdateBranch, ::Gitaly::UserUpdateBranchRequest, ::Gitaly::UserUpdateBranchResponse
-      # This comment is left unintentionally blank.
+      # UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes
+      # hooks and contacts Rails to verify that the user is indeed allowed to delete that branch. The
+      # following known error conditions may happen:
+      #
+      # - Returns `InvalidArgument` in case either the branch name or user are not set.
+      # - Returns `FailedPrecondition` in case the branch does not exist.
+      # - Returns `OK` with a `PreReceiveError` in case custom hooks refused the update.
+      # - Returns `FailedPrecondition` in case updating the reference fails because of a concurrent
+      #   write to the same reference.
       rpc :UserDeleteBranch, ::Gitaly::UserDeleteBranchRequest, ::Gitaly::UserDeleteBranchResponse
       # UserCreateTag creates a new tag.
       rpc :UserCreateTag, ::Gitaly::UserCreateTagRequest, ::Gitaly::UserCreateTagResponse