proto: Add missing docs for GetRawChanges RPC

3 files changed, 53 insertions, 49 deletions

diff --git a/proto/go/gitalypb/repository.pb.go b/proto/go/gitalypb/repository.pb.go
index 44a0a0555..81a4efe6a 100644
--- a/proto/go/gitalypb/repository.pb.go
+++ b/proto/go/gitalypb/repository.pb.go
@@ -77,23 +77,24 @@ func (GetArchiveRequest_Format) EnumDescriptor() ([]byte, []int) {
 	return file_repository_proto_rawDescGZIP(), []int{18, 0}
 }
 
-// Operation ...
+// Operation is the change that occurred on the file. Consult the man pages
+// for git-diff(1) for additional detail on the semantics of each operation.
 type GetRawChangesResponse_RawChange_Operation int32
 
 const (
-	// UNKNOWN ...
+	// UNKNOWN
 	GetRawChangesResponse_RawChange_UNKNOWN GetRawChangesResponse_RawChange_Operation = 0 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
-	// ADDED ...
+	// ADDED
 	GetRawChangesResponse_RawChange_ADDED GetRawChangesResponse_RawChange_Operation = 1 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-	// COPIED ...
+	// COPIED
 	GetRawChangesResponse_RawChange_COPIED GetRawChangesResponse_RawChange_Operation = 2 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-	// DELETED ...
+	// DELETED
 	GetRawChangesResponse_RawChange_DELETED GetRawChangesResponse_RawChange_Operation = 3 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-	// MODIFIED ...
+	// MODIFIED
 	GetRawChangesResponse_RawChange_MODIFIED GetRawChangesResponse_RawChange_Operation = 4 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-	// RENAMED ...
+	// RENAMED
 	GetRawChangesResponse_RawChange_RENAMED GetRawChangesResponse_RawChange_Operation = 5 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-	// TYPE_CHANGED ...
+	// TYPE_CHANGED
 	GetRawChangesResponse_RawChange_TYPE_CHANGED GetRawChangesResponse_RawChange_Operation = 6 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
 )
 
@@ -3541,17 +3542,18 @@ func (*CreateRepositoryFromSnapshotResponse) Descriptor() ([]byte, []int) {
 	return file_repository_proto_rawDescGZIP(), []int{59}
 }
 
-// GetRawChangesRequest ...
+// GetRawChangesRequest is a request for the GetRawChanges RPC.
 type GetRawChangesRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository ...
+	// repository is the repository to run the diff in. The storage_name and
+	// relative_path attributes must be provided.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// from_revision ...
+	// from_revision is the Git revision to start the diff at.
 	FromRevision string `protobuf:"bytes,2,opt,name=from_revision,json=fromRevision,proto3" json:"from_revision,omitempty"`
-	// to_revision ...
+	// to_revision is the Git revision to end the diff at.
 	ToRevision string `protobuf:"bytes,3,opt,name=to_revision,json=toRevision,proto3" json:"to_revision,omitempty"`
 }
 
@@ -3608,13 +3610,13 @@ func (x *GetRawChangesRequest) GetToRevision() string {
 	return ""
 }
 
-// GetRawChangesResponse ...
+// GetRawChangesResponse is a response for the GetRawChanges RPC.
 type GetRawChangesResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// raw_changes ...
+	// raw_changes is the set of changes between the two revisions.
 	RawChanges []*GetRawChangesResponse_RawChange `protobuf:"bytes,1,rep,name=raw_changes,json=rawChanges,proto3" json:"raw_changes,omitempty"`
 }
 
@@ -5327,28 +5329,28 @@ func (x *RepositoryInfoResponse_ObjectsInfo) GetKeepSize() uint64 {
 	return 0
 }
 
-// RawChange ...
+// RawChange represents the metadata for a single change between the two
+// revisions.
 type GetRawChangesResponse_RawChange struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// blob_id ...
+	// blob_id is the OID of the file that was changed.
 	BlobId string `protobuf:"bytes,1,opt,name=blob_id,json=blobId,proto3" json:"blob_id,omitempty"`
-	// size ...
+	// size is the blob size in bytes.
 	Size int64 `protobuf:"varint,2,opt,name=size,proto3" json:"size,omitempty"`
-	// operation ...
+	// operation is the change that occurred on the file.
 	Operation GetRawChangesResponse_RawChange_Operation `protobuf:"varint,5,opt,name=operation,proto3,enum=gitaly.GetRawChangesResponse_RawChange_Operation" json:"operation,omitempty"`
 	// raw_operation ...
 	RawOperation string `protobuf:"bytes,6,opt,name=raw_operation,json=rawOperation,proto3" json:"raw_operation,omitempty"`
-	// old_mode ...
+	// old_mode is the previous mode of the file. This may be equal to new_mode.
 	OldMode int32 `protobuf:"varint,7,opt,name=old_mode,json=oldMode,proto3" json:"old_mode,omitempty"`
-	// new_mode ...
+	// new_mode is the current mode of the file. This may be equal to old_mode.
 	NewMode int32 `protobuf:"varint,8,opt,name=new_mode,json=newMode,proto3" json:"new_mode,omitempty"`
-	// new_path_bytes ...
-	// the following fields, 9 and 10, will eventually replace 3 and 4
+	// new_path_bytes is the new file path. This may be equal to old_path_bytes.
 	NewPathBytes []byte `protobuf:"bytes,9,opt,name=new_path_bytes,json=newPathBytes,proto3" json:"new_path_bytes,omitempty"`
-	// old_path_bytes ...
+	// old_path_bytes is the old file path. This may be equal to new_path_bytes.
 	OldPathBytes []byte `protobuf:"bytes,10,opt,name=old_path_bytes,json=oldPathBytes,proto3" json:"old_path_bytes,omitempty"`
 }
 
diff --git a/proto/go/gitalypb/repository_grpc.pb.go b/proto/go/gitalypb/repository_grpc.pb.go
index 1884c232a..c74136fc6 100644
--- a/proto/go/gitalypb/repository_grpc.pb.go
+++ b/proto/go/gitalypb/repository_grpc.pb.go
@@ -121,7 +121,7 @@ type RepositoryServiceClient interface {
 	// CreateRepositoryFromSnapshot creates a new repository based on a snapshot created with
 	// the GetSnapshot RPC. The snapshot is fetched via HTTP.
 	CreateRepositoryFromSnapshot(ctx context.Context, in *CreateRepositoryFromSnapshotRequest, opts ...grpc.CallOption) (*CreateRepositoryFromSnapshotResponse, error)
-	// GetRawChanges ...
+	// GetRawChanges returns metadata in raw format on the changes between two revisions.
 	GetRawChanges(ctx context.Context, in *GetRawChangesRequest, opts ...grpc.CallOption) (RepositoryService_GetRawChangesClient, error)
 	// SearchFilesByContent ...
 	SearchFilesByContent(ctx context.Context, in *SearchFilesByContentRequest, opts ...grpc.CallOption) (RepositoryService_SearchFilesByContentClient, error)
@@ -1093,7 +1093,7 @@ type RepositoryServiceServer interface {
 	// CreateRepositoryFromSnapshot creates a new repository based on a snapshot created with
 	// the GetSnapshot RPC. The snapshot is fetched via HTTP.
 	CreateRepositoryFromSnapshot(context.Context, *CreateRepositoryFromSnapshotRequest) (*CreateRepositoryFromSnapshotResponse, error)
-	// GetRawChanges ...
+	// GetRawChanges returns metadata in raw format on the changes between two revisions.
 	GetRawChanges(*GetRawChangesRequest, RepositoryService_GetRawChangesServer) error
 	// SearchFilesByContent ...
 	SearchFilesByContent(*SearchFilesByContentRequest, RepositoryService_SearchFilesByContentServer) error
diff --git a/proto/repository.proto b/proto/repository.proto
index 1576a0c67..bf959a66f 100644
--- a/proto/repository.proto
+++ b/proto/repository.proto
@@ -239,7 +239,7 @@ service RepositoryService {
     };
   }
 
-  // GetRawChanges ...
+  // GetRawChanges returns metadata in raw format on the changes between two revisions.
   rpc GetRawChanges(GetRawChangesRequest) returns (stream GetRawChangesResponse) {
     option (op_type) = {
       op: ACCESSOR
@@ -1003,41 +1003,44 @@ message CreateRepositoryFromSnapshotRequest {
 message CreateRepositoryFromSnapshotResponse {
 }
 
-// GetRawChangesRequest ...
+// GetRawChangesRequest is a request for the GetRawChanges RPC.
 message GetRawChangesRequest {
-  // repository ...
+  // repository is the repository to run the diff in. The storage_name and
+  // relative_path attributes must be provided.
   Repository repository = 1 [(target_repository)=true];
-  // from_revision ...
+  // from_revision is the Git revision to start the diff at.
   string from_revision = 2;
-  // to_revision ...
+  // to_revision is the Git revision to end the diff at.
   string to_revision = 3;
 }
 
-// GetRawChangesResponse ...
+// GetRawChangesResponse is a response for the GetRawChanges RPC.
 message GetRawChangesResponse {
-  // RawChange ...
+  // RawChange represents the metadata for a single change between the two
+  // revisions.
   message RawChange {
-    // Operation ...
+    // Operation is the change that occurred on the file. Consult the man pages
+    // for git-diff(1) for additional detail on the semantics of each operation.
     enum Operation {
-      // UNKNOWN ...
+      // UNKNOWN
       UNKNOWN = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
-      // ADDED ...
+      // ADDED
       ADDED = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-      // COPIED ...
+      // COPIED
       COPIED = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-      // DELETED ...
+      // DELETED
       DELETED = 3; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-      // MODIFIED ...
+      // MODIFIED
       MODIFIED = 4; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-      // RENAMED ...
+      // RENAMED
       RENAMED = 5; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-      // TYPE_CHANGED ...
+      // TYPE_CHANGED
       TYPE_CHANGED = 6; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
     }
 
-    // blob_id ...
+    // blob_id is the OID of the file that was changed.
     string blob_id = 1;
-    // size ...
+    // size is the blob size in bytes.
     int64 size = 2;
 
     // This used to be a string that is now represented by the field 9 as byte array.
@@ -1047,23 +1050,22 @@ message GetRawChangesResponse {
     reserved 4;
     reserved "old_path";
 
-    // operation ...
+    // operation is the change that occurred on the file.
     Operation operation = 5;
     // raw_operation ...
     string raw_operation = 6;
-    // old_mode ...
+    // old_mode is the previous mode of the file. This may be equal to new_mode.
     int32 old_mode = 7;
-    // new_mode ...
+    // new_mode is the current mode of the file. This may be equal to old_mode.
     int32 new_mode = 8;
 
-    // new_path_bytes ...
-    // the following fields, 9 and 10, will eventually replace 3 and 4
+    // new_path_bytes is the new file path. This may be equal to old_path_bytes.
     bytes new_path_bytes = 9;
-    // old_path_bytes ...
+    // old_path_bytes is the old file path. This may be equal to new_path_bytes.
     bytes old_path_bytes = 10;
   }
 
-  // raw_changes ...
+  // raw_changes is the set of changes between the two revisions.
   repeated RawChange raw_changes = 1;
 }