proto: Improve documentation for UserCreateTags

Improve the documentation for our Protobuf definitions of
UserCreateTags.

4 files changed, 36 insertions, 26 deletions

diff --git a/proto/go/gitalypb/operations.pb.go b/proto/go/gitalypb/operations.pb.go
index 5d068306c..8d2fcb742 100644
--- a/proto/go/gitalypb/operations.pb.go
+++ b/proto/go/gitalypb/operations.pb.go
@@ -806,26 +806,29 @@ func (x *UserDeleteTagResponse) GetPreReceiveError() string {
 	return ""
 }
 
-// This comment is left unintentionally blank.
+// UserCreateTagRequest is a request for the UserCreateTag RPC.
 type UserCreateTagRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository is the repository in which the tag shall be created.
+	// Repository is the repository in which the tag shall be created.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// tag_name is the name of the tag that shall be created.
+	// TagName is the name of the tag that shall be created. Note that this should be set to the name
+	// only: if you want to create a tag `refs/heads/v1.0`, you need to pass `v1.0` as TagName.
 	TagName []byte `protobuf:"bytes,2,opt,name=tag_name,json=tagName,proto3" json:"tag_name,omitempty"`
-	// user is the user as which the tag shall be created.
+	// User is the user as which the tag shall be created. This user is used to perform access checks
+	// against Rails' `/internal/allowed` endpoint.
 	User *User `protobuf:"bytes,3,opt,name=user,proto3" json:"user,omitempty"`
-	// target_revision is the revision which the tag should point to.
+	// TargetRevision is the revision that the newly created tag should be pointing to. Note that if
+	// the revision points to a tag, that tag will be peeled to the commit it is pointing to. If the
+	// TargetRevision does not point to a commit then the RPC will return an error.
 	TargetRevision []byte `protobuf:"bytes,4,opt,name=target_revision,json=targetRevision,proto3" json:"target_revision,omitempty"`
-	// message is the message of the tag. If it is empty, a lightweight tag is
-	// created. Otherwise, an annotated tag is created.
+	// Message is the message of the tag. If it is empty, a lightweight tag is created. Otherwise, an
+	// annotated tag is created.
 	Message []byte `protobuf:"bytes,5,opt,name=message,proto3" json:"message,omitempty"`
-	// timestamp is the optional timestamp to use for the created tag tags. If
-	// it's not set, the current time will be used. It's only used if an
-	// annotated tag is being created.
+	// Timestamp is the optional timestamp to use for the created tag tags. If it's not set, the
+	// current time will be used. It's only used if an annotated tag is being created.
 	Timestamp *timestamppb.Timestamp `protobuf:"bytes,7,opt,name=timestamp,proto3" json:"timestamp,omitempty"`
 }
 
@@ -903,7 +906,7 @@ func (x *UserCreateTagRequest) GetTimestamp() *timestamppb.Timestamp {
 	return nil
 }
 
-// This comment is left unintentionally blank.
+// UserCreateTagResponse is a response for the UserCreateTag RPC.
 type UserCreateTagResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
diff --git a/proto/go/gitalypb/operations_grpc.pb.go b/proto/go/gitalypb/operations_grpc.pb.go
index e2538ab0e..f472462dc 100644
--- a/proto/go/gitalypb/operations_grpc.pb.go
+++ b/proto/go/gitalypb/operations_grpc.pb.go
@@ -41,7 +41,8 @@ type OperationServiceClient interface {
 	//   `gitaly_user_delete_branch_structured_errors` feature flag is set this error case will
 	//   instead return `FailedPrecondition` with a `ReferenceUpdate` structured error.
 	UserDeleteBranch(ctx context.Context, in *UserDeleteBranchRequest, opts ...grpc.CallOption) (*UserDeleteBranchResponse, error)
-	// UserCreateTag creates a new tag.
+	// UserCreateTag creates a new tag. This RPC knows to create both lightweight and annotated tags
+	// depending on whether a message is set.
 	UserCreateTag(ctx context.Context, in *UserCreateTagRequest, opts ...grpc.CallOption) (*UserCreateTagResponse, error)
 	// This comment is left unintentionally blank.
 	UserDeleteTag(ctx context.Context, in *UserDeleteTagRequest, opts ...grpc.CallOption) (*UserDeleteTagResponse, error)
@@ -356,7 +357,8 @@ type OperationServiceServer interface {
 	//   `gitaly_user_delete_branch_structured_errors` feature flag is set this error case will
 	//   instead return `FailedPrecondition` with a `ReferenceUpdate` structured error.
 	UserDeleteBranch(context.Context, *UserDeleteBranchRequest) (*UserDeleteBranchResponse, error)
-	// UserCreateTag creates a new tag.
+	// UserCreateTag creates a new tag. This RPC knows to create both lightweight and annotated tags
+	// depending on whether a message is set.
 	UserCreateTag(context.Context, *UserCreateTagRequest) (*UserCreateTagResponse, error)
 	// This comment is left unintentionally blank.
 	UserDeleteTag(context.Context, *UserDeleteTagRequest) (*UserDeleteTagResponse, error)
diff --git a/proto/operations.proto b/proto/operations.proto
index f4d41a8ad..a4bf93b6d 100644
--- a/proto/operations.proto
+++ b/proto/operations.proto
@@ -49,7 +49,8 @@ service OperationService {
     };
   }
 
-  // UserCreateTag creates a new tag.
+  // UserCreateTag creates a new tag. This RPC knows to create both lightweight and annotated tags
+  // depending on whether a message is set.
   rpc UserCreateTag(UserCreateTagRequest) returns (UserCreateTagResponse) {
     option (op_type) = {
       op: MUTATOR
@@ -257,26 +258,29 @@ message UserDeleteTagResponse {
   string pre_receive_error = 1;
 }
 
-// This comment is left unintentionally blank.
+// UserCreateTagRequest is a request for the UserCreateTag RPC.
 message UserCreateTagRequest {
-  // repository is the repository in which the tag shall be created.
+  // Repository is the repository in which the tag shall be created.
   Repository repository = 1 [(target_repository)=true];
-  // tag_name is the name of the tag that shall be created.
+  // TagName is the name of the tag that shall be created. Note that this should be set to the name
+  // only: if you want to create a tag `refs/heads/v1.0`, you need to pass `v1.0` as TagName.
   bytes tag_name = 2;
-  // user is the user as which the tag shall be created.
+  // User is the user as which the tag shall be created. This user is used to perform access checks
+  // against Rails' `/internal/allowed` endpoint.
   User user = 3;
-  // target_revision is the revision which the tag should point to.
+  // TargetRevision is the revision that the newly created tag should be pointing to. Note that if
+  // the revision points to a tag, that tag will be peeled to the commit it is pointing to. If the
+  // TargetRevision does not point to a commit then the RPC will return an error.
   bytes target_revision = 4;
-  // message is the message of the tag. If it is empty, a lightweight tag is
-  // created. Otherwise, an annotated tag is created.
+  // Message is the message of the tag. If it is empty, a lightweight tag is created. Otherwise, an
+  // annotated tag is created.
   bytes message = 5;
-  // timestamp is the optional timestamp to use for the created tag tags. If
-  // it's not set, the current time will be used. It's only used if an
-  // annotated tag is being created.
+  // Timestamp is the optional timestamp to use for the created tag tags. If it's not set, the
+  // current time will be used. It's only used if an annotated tag is being created.
   google.protobuf.Timestamp timestamp = 7;
 }
 
-// This comment is left unintentionally blank.
+// UserCreateTagResponse is a response for the UserCreateTag RPC.
 message UserCreateTagResponse {
   // tag is the newly created tag.
   Tag tag = 1;
diff --git a/ruby/proto/gitaly/operations_services_pb.rb b/ruby/proto/gitaly/operations_services_pb.rb
index c7e22ac03..f2a427687 100644
--- a/ruby/proto/gitaly/operations_services_pb.rb
+++ b/ruby/proto/gitaly/operations_services_pb.rb
@@ -37,7 +37,8 @@ module Gitaly
       #   `gitaly_user_delete_branch_structured_errors` feature flag is set this error case will
       #   instead return `FailedPrecondition` with a `ReferenceUpdate` structured error.
       rpc :UserDeleteBranch, ::Gitaly::UserDeleteBranchRequest, ::Gitaly::UserDeleteBranchResponse
-      # UserCreateTag creates a new tag.
+      # UserCreateTag creates a new tag. This RPC knows to create both lightweight and annotated tags
+      # depending on whether a message is set.
       rpc :UserCreateTag, ::Gitaly::UserCreateTagRequest, ::Gitaly::UserCreateTagResponse
       # This comment is left unintentionally blank.
       rpc :UserDeleteTag, ::Gitaly::UserDeleteTagRequest, ::Gitaly::UserDeleteTagResponse