proto: Document the CommitLanguages rpc

We're about to make some changes in the handling of the CommitLanguages
rpc, and because I noticed this RPC did not have any documentation, I've
decided to add it.

4 files changed, 38 insertions, 26 deletions

diff --git a/proto/commit.proto b/proto/commit.proto
index 4aaa7f086..b710712d8 100644
--- a/proto/commit.proto
+++ b/proto/commit.proto
@@ -99,7 +99,8 @@ service CommitService {
     };
   }
 
-  // This comment is left unintentionally blank.
+  // CommitLanguages detects the source code languages of the whole tree for a
+  // given commit. Returns an error in case no languages could be detected.
   rpc CommitLanguages(CommitLanguagesRequest) returns (CommitLanguagesResponse) {
     option (op_type) = {
       op: ACCESSOR
@@ -609,31 +610,35 @@ message FindCommitsResponse {
   repeated GitCommit commits = 1;
 }
 
-// This comment is left unintentionally blank.
+// CommitLanguagesRequest requests to detect the source code languages.
 message CommitLanguagesRequest {
-  // This comment is left unintentionally blank.
+  // Repository is the repository where to detect the languages in.
   Repository repository = 1 [(target_repository)=true];
-  // This comment is left unintentionally blank.
+  // Revision tells for which commit the languages should be detected. If it's
+  // omitted, the HEAD commit of the default branch is used.
   bytes revision = 2;
 }
 
-// This comment is left unintentionally blank.
+// CommitLanguagesResponse returns the language statistics.
 message CommitLanguagesResponse {
-  // This comment is left unintentionally blank.
+  // Language specifies the statistics for one language.
   message Language {
-    // This comment is left unintentionally blank.
+    // Name is the name of the detected language, for example: Ruby, Go, HTML
+    // A full list of language names can be found at:
+    // https://github.com/github/linguist/blob/master/lib/linguist/languages.yml
     string name = 1;
-    // This comment is left unintentionally blank.
+    // Share is the percentual share (value between 0 and 100) of this language
+    // in relation to other languages that exist in the given revision.
     float share = 2;
-    // This comment is left unintentionally blank.
+    // Color specifies the associated color for this language, for example #3fd5e0.
     string color = 3;
-    // This comment is left unintentionally blank.
+    // FileCount tells how many files with this language are found.
     uint32 file_count = 4;
-    // This comment is left unintentionally blank.
+    // Bytes is the total amount of bytes written in this language
     uint64 bytes = 5;
   }
 
-  // This comment is left unintentionally blank.
+  // Languages is a set of all the detected languages and their statistics.
   repeated Language languages = 1;
 }
 
diff --git a/proto/go/gitalypb/commit.pb.go b/proto/go/gitalypb/commit.pb.go
index 98ff1ce0c..2c168fd0a 100644
--- a/proto/go/gitalypb/commit.pb.go
+++ b/proto/go/gitalypb/commit.pb.go
@@ -2444,15 +2444,16 @@ func (x *FindCommitsResponse) GetCommits() []*GitCommit {
 	return nil
 }
 
-// This comment is left unintentionally blank.
+// CommitLanguagesRequest requests to detect the source code languages.
 type CommitLanguagesRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// This comment is left unintentionally blank.
+	// Repository is the repository where to detect the languages in.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// This comment is left unintentionally blank.
+	// Revision tells for which commit the languages should be detected. If it's
+	// omitted, the HEAD commit of the default branch is used.
 	Revision []byte `protobuf:"bytes,2,opt,name=revision,proto3" json:"revision,omitempty"`
 }
 
@@ -2502,13 +2503,13 @@ func (x *CommitLanguagesRequest) GetRevision() []byte {
 	return nil
 }
 
-// This comment is left unintentionally blank.
+// CommitLanguagesResponse returns the language statistics.
 type CommitLanguagesResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// This comment is left unintentionally blank.
+	// Languages is a set of all the detected languages and their statistics.
 	Languages []*CommitLanguagesResponse_Language `protobuf:"bytes,1,rep,name=languages,proto3" json:"languages,omitempty"`
 }
 
@@ -3754,21 +3755,24 @@ func (x *ListCommitsByRefNameResponse_CommitForRef) GetRefName() []byte {
 	return nil
 }
 
-// This comment is left unintentionally blank.
+// Language specifies the statistics for one language.
 type CommitLanguagesResponse_Language struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// This comment is left unintentionally blank.
+	// Name is the name of the detected language, for example: Ruby, Go, HTML
+	// A full list of language names can be found at:
+	// https://github.com/github/linguist/blob/master/lib/linguist/languages.yml
 	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
-	// This comment is left unintentionally blank.
+	// Share is the percentual share (value between 0 and 100) of this language
+	// in relation to other languages that exist in the given revision.
 	Share float32 `protobuf:"fixed32,2,opt,name=share,proto3" json:"share,omitempty"`
-	// This comment is left unintentionally blank.
+	// Color specifies the associated color for this language, for example #3fd5e0.
 	Color string `protobuf:"bytes,3,opt,name=color,proto3" json:"color,omitempty"`
-	// This comment is left unintentionally blank.
+	// FileCount tells how many files with this language are found.
 	FileCount uint32 `protobuf:"varint,4,opt,name=file_count,json=fileCount,proto3" json:"file_count,omitempty"`
-	// This comment is left unintentionally blank.
+	// Bytes is the total amount of bytes written in this language
 	Bytes uint64 `protobuf:"varint,5,opt,name=bytes,proto3" json:"bytes,omitempty"`
 }
 
diff --git a/proto/go/gitalypb/commit_grpc.pb.go b/proto/go/gitalypb/commit_grpc.pb.go
index 4a32b22c5..4fb2773d2 100644
--- a/proto/go/gitalypb/commit_grpc.pb.go
+++ b/proto/go/gitalypb/commit_grpc.pb.go
@@ -49,7 +49,8 @@ type CommitServiceClient interface {
 	FindAllCommits(ctx context.Context, in *FindAllCommitsRequest, opts ...grpc.CallOption) (CommitService_FindAllCommitsClient, error)
 	// This comment is left unintentionally blank.
 	FindCommits(ctx context.Context, in *FindCommitsRequest, opts ...grpc.CallOption) (CommitService_FindCommitsClient, error)
-	// This comment is left unintentionally blank.
+	// CommitLanguages detects the source code languages of the whole tree for a
+	// given commit. Returns an error in case no languages could be detected.
 	CommitLanguages(ctx context.Context, in *CommitLanguagesRequest, opts ...grpc.CallOption) (*CommitLanguagesResponse, error)
 	// This comment is left unintentionally blank.
 	RawBlame(ctx context.Context, in *RawBlameRequest, opts ...grpc.CallOption) (CommitService_RawBlameClient, error)
@@ -688,7 +689,8 @@ type CommitServiceServer interface {
 	FindAllCommits(*FindAllCommitsRequest, CommitService_FindAllCommitsServer) error
 	// This comment is left unintentionally blank.
 	FindCommits(*FindCommitsRequest, CommitService_FindCommitsServer) error
-	// This comment is left unintentionally blank.
+	// CommitLanguages detects the source code languages of the whole tree for a
+	// given commit. Returns an error in case no languages could be detected.
 	CommitLanguages(context.Context, *CommitLanguagesRequest) (*CommitLanguagesResponse, error)
 	// This comment is left unintentionally blank.
 	RawBlame(*RawBlameRequest, CommitService_RawBlameServer) error
diff --git a/ruby/proto/gitaly/commit_services_pb.rb b/ruby/proto/gitaly/commit_services_pb.rb
index 17df1b4b8..c99e663fb 100644
--- a/ruby/proto/gitaly/commit_services_pb.rb
+++ b/ruby/proto/gitaly/commit_services_pb.rb
@@ -43,7 +43,8 @@ module Gitaly
       rpc :FindAllCommits, ::Gitaly::FindAllCommitsRequest, stream(::Gitaly::FindAllCommitsResponse)
       # This comment is left unintentionally blank.
       rpc :FindCommits, ::Gitaly::FindCommitsRequest, stream(::Gitaly::FindCommitsResponse)
-      # This comment is left unintentionally blank.
+      # CommitLanguages detects the source code languages of the whole tree for a
+      # given commit. Returns an error in case no languages could be detected.
       rpc :CommitLanguages, ::Gitaly::CommitLanguagesRequest, ::Gitaly::CommitLanguagesResponse
       # This comment is left unintentionally blank.
       rpc :RawBlame, ::Gitaly::RawBlameRequest, stream(::Gitaly::RawBlameResponse)