proto: Document UserDeleteBranch RPC

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

2 files changed, 29 insertions, 8 deletions

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)