proto: Enforce comment-linting for services

Enforce that services must have a comment and add a placeholder for all
instances where such a comment is missing.

35 files changed, 74 insertions, 1 deletions

diff --git a/proto/.protolint.yaml b/proto/.protolint.yaml
index 43f94a8a8..c415ec768 100644
--- a/proto/.protolint.yaml
+++ b/proto/.protolint.yaml
@@ -16,7 +16,6 @@ lint:
       - FILE_HAS_COMMENT
       - RPCS_HAVE_COMMENT
       - FIELDS_HAVE_COMMENT
-      - SERVICES_HAVE_COMMENT
       - MESSAGES_HAVE_COMMENT
       - ENUMS_HAVE_COMMENT
       - ENUM_FIELDS_HAVE_COMMENT
diff --git a/proto/blob.proto b/proto/blob.proto
index 528615f73..f6ded95b8 100644
--- a/proto/blob.proto
+++ b/proto/blob.proto
@@ -7,6 +7,8 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// BlobService is a service which provides RPCs to retrieve Git blobs from a
+// specific repository.
 service BlobService {
   // GetBlob returns the contents of a blob object referenced by its object
   // ID. We use a stream to return a chunked arbitrarily large binary
diff --git a/proto/cleanup.proto b/proto/cleanup.proto
index 07e8ad72f..13e575785 100644
--- a/proto/cleanup.proto
+++ b/proto/cleanup.proto
@@ -7,6 +7,7 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// CleanupService provides RPCs to clean up a repository's contents.
 service CleanupService {
   rpc ApplyBfgObjectMapStream(stream ApplyBfgObjectMapStreamRequest) returns (stream ApplyBfgObjectMapStreamResponse) {
     option (op_type) = {
diff --git a/proto/commit.proto b/proto/commit.proto
index 5c5de630b..f61fffb35 100644
--- a/proto/commit.proto
+++ b/proto/commit.proto
@@ -8,6 +8,8 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// CommitService is a service which provides RPCs that interact with Git
+// commits.
 service CommitService {
 
   // ListCommits lists all commits reachable via a set of references by doing a
diff --git a/proto/conflicts.proto b/proto/conflicts.proto
index bad601963..25eb0965e 100644
--- a/proto/conflicts.proto
+++ b/proto/conflicts.proto
@@ -8,6 +8,8 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// ConflictsService is a service which provides RPCs to interact with conflicts
+// resulting from a merge.
 service ConflictsService {
   rpc ListConflictFiles(ListConflictFilesRequest) returns (stream ListConflictFilesResponse) {
     option (op_type) = {
diff --git a/proto/diff.proto b/proto/diff.proto
index 536cc675f..8ff8347a0 100644
--- a/proto/diff.proto
+++ b/proto/diff.proto
@@ -7,6 +7,8 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// DiffService is a service which provides RPCs to inspect differences
+// introduced between a set of commits.
 service DiffService {
   // Returns stream of CommitDiffResponse with patches chunked over messages
   rpc CommitDiff(CommitDiffRequest) returns (stream CommitDiffResponse) {
diff --git a/proto/hook.proto b/proto/hook.proto
index 2aa7ce855..960c898ba 100644
--- a/proto/hook.proto
+++ b/proto/hook.proto
@@ -7,6 +7,9 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// HookService is a service which provides the implementation of a subset of
+// Git hooks. These are typically invoked via the `gitaly-hooks` binary to
+// ensure that the actual hook logic is executed in the context of the server.
 service HookService {
   rpc PreReceiveHook(stream PreReceiveHookRequest) returns (stream PreReceiveHookResponse) {
     option (op_type) = {
diff --git a/proto/namespace.proto b/proto/namespace.proto
index e81ef7224..cc23a35ca 100644
--- a/proto/namespace.proto
+++ b/proto/namespace.proto
@@ -6,6 +6,9 @@ import "lint.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// NamespaceService is a service which provides RPCs to manage namespaces of a
+// storage. Namespaces had been used before Gitaly migrated to hashed storages
+// and shouldn't be used nowadays anymore.
 service NamespaceService {
   rpc AddNamespace(AddNamespaceRequest) returns (AddNamespaceResponse) {
     option (op_type) = {
diff --git a/proto/objectpool.proto b/proto/objectpool.proto
index 748370e31..8258e09db 100644
--- a/proto/objectpool.proto
+++ b/proto/objectpool.proto
@@ -7,6 +7,10 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// ObjectPoolService is a service containing RPCs to manipulate object pools.
+// An object pool is a separate repository that can be linked to from multiple
+// satellite repositories in order to deduplicate common objects between them.
+// This is mostly used in the contexet of repository forks.
 service ObjectPoolService {
   rpc CreateObjectPool(CreateObjectPoolRequest) returns (CreateObjectPoolResponse) {
     option (op_type) = {
diff --git a/proto/praefect.proto b/proto/praefect.proto
index dd3acb431..917be6ebb 100644
--- a/proto/praefect.proto
+++ b/proto/praefect.proto
@@ -8,6 +8,8 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// PraefectInfoService is a service which provides RPCs to query and modify
+// Praefect-specific parameters.
 service PraefectInfoService {
   option (intercepted) = true;
 
diff --git a/proto/ref.proto b/proto/ref.proto
index b3697b540..8980e6443 100644
--- a/proto/ref.proto
+++ b/proto/ref.proto
@@ -8,6 +8,7 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// RefService is a service that provides RPCs to list and modify Git references.
 service RefService {
   rpc FindDefaultBranchName(FindDefaultBranchNameRequest) returns (FindDefaultBranchNameResponse) {
     option (op_type) = {
diff --git a/proto/remote.proto b/proto/remote.proto
index 869f96331..003c06105 100644
--- a/proto/remote.proto
+++ b/proto/remote.proto
@@ -7,6 +7,8 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// RemoteService is a service providing RPCs to interact with a remote
+// repository that is hosted on another Git server.
 service RemoteService {
 
   // UpdateRemoteMirror compares the references in the target repository and its remote mirror
diff --git a/proto/repository.proto b/proto/repository.proto
index ad6c06f09..c203ac2db 100644
--- a/proto/repository.proto
+++ b/proto/repository.proto
@@ -7,6 +7,7 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// RepositoryService is a service providing RPCs accessing repositories as a whole.
 service RepositoryService {
   rpc RepositoryExists(RepositoryExistsRequest) returns (RepositoryExistsResponse) {
     option (op_type) = {
diff --git a/proto/server.proto b/proto/server.proto
index 35be64925..fc5901036 100644
--- a/proto/server.proto
+++ b/proto/server.proto
@@ -6,6 +6,7 @@ import "lint.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// ServerService is a service that provides information about a Gitaly server.
 service ServerService {
   option (intercepted) = true;
 
diff --git a/proto/smarthttp.proto b/proto/smarthttp.proto
index 2b8fdc97f..c1d4fd83f 100644
--- a/proto/smarthttp.proto
+++ b/proto/smarthttp.proto
@@ -7,6 +7,8 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// SmartHTTPService is a service that provides RPCs required for HTTP-based Git
+// clones via the smart HTTP protocol.
 service SmartHTTPService {
   // The response body for GET /info/refs?service=git-upload-pack
   // Will be invoked when the user executes a `git fetch`, meaning the server
diff --git a/proto/ssh.proto b/proto/ssh.proto
index fbbb734bd..45b64c004 100644
--- a/proto/ssh.proto
+++ b/proto/ssh.proto
@@ -7,6 +7,7 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// SSHService is a service that provides RPCs required for SSH-based Git clones.
 service SSHService {
   // To forward 'git upload-pack' to Gitaly for SSH sessions
   rpc SSHUploadPack(stream SSHUploadPackRequest) returns (stream SSHUploadPackResponse) {
diff --git a/proto/transaction.proto b/proto/transaction.proto
index a21b402e7..7d074f898 100644
--- a/proto/transaction.proto
+++ b/proto/transaction.proto
@@ -7,6 +7,11 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// RefTransaction is a service which provides RPCs to interact with reference
+// transactions. Reference transactions are used in the context of Gitaly
+// Cluster to ensure that all nodes part of a single transaction perform the
+// same change: given a set of changes, the changes are hashed and the hash is
+// then voted on.
 service RefTransaction {
   option (intercepted) = true;
 
diff --git a/proto/wiki.proto b/proto/wiki.proto
index 80c34b522..bf5f62320 100644
--- a/proto/wiki.proto
+++ b/proto/wiki.proto
@@ -7,6 +7,9 @@ import "shared.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// WikiService is a service that provides Wiki-related functionality. This
+// service is deprecated and should not be used anymore. Instead, all
+// functionality to implement Wikis should use Git-based RPCS.
 service WikiService {
   rpc WikiWritePage(stream WikiWritePageRequest) returns (WikiWritePageResponse) {
     option (op_type) = {
diff --git a/ruby/proto/gitaly/blob_services_pb.rb b/ruby/proto/gitaly/blob_services_pb.rb
index 5eb951f5e..1e726517b 100644
--- a/ruby/proto/gitaly/blob_services_pb.rb
+++ b/ruby/proto/gitaly/blob_services_pb.rb
@@ -6,6 +6,8 @@ require 'blob_pb'
 
 module Gitaly
   module BlobService
+    # BlobService is a service which provides RPCs to retrieve Git blobs from a
+    # specific repository.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/cleanup_services_pb.rb b/ruby/proto/gitaly/cleanup_services_pb.rb
index 643b2ea70..6fdbd4304 100644
--- a/ruby/proto/gitaly/cleanup_services_pb.rb
+++ b/ruby/proto/gitaly/cleanup_services_pb.rb
@@ -6,6 +6,7 @@ require 'cleanup_pb'
 
 module Gitaly
   module CleanupService
+    # CleanupService provides RPCs to clean up a repository's contents.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/commit_services_pb.rb b/ruby/proto/gitaly/commit_services_pb.rb
index 131f84122..0551e05de 100644
--- a/ruby/proto/gitaly/commit_services_pb.rb
+++ b/ruby/proto/gitaly/commit_services_pb.rb
@@ -6,6 +6,8 @@ require 'commit_pb'
 
 module Gitaly
   module CommitService
+    # CommitService is a service which provides RPCs that interact with Git
+    # commits.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/conflicts_services_pb.rb b/ruby/proto/gitaly/conflicts_services_pb.rb
index 0332407f8..344f5afa2 100644
--- a/ruby/proto/gitaly/conflicts_services_pb.rb
+++ b/ruby/proto/gitaly/conflicts_services_pb.rb
@@ -6,6 +6,8 @@ require 'conflicts_pb'
 
 module Gitaly
   module ConflictsService
+    # ConflictsService is a service which provides RPCs to interact with conflicts
+    # resulting from a merge.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/diff_services_pb.rb b/ruby/proto/gitaly/diff_services_pb.rb
index 55807f77a..071c98c36 100644
--- a/ruby/proto/gitaly/diff_services_pb.rb
+++ b/ruby/proto/gitaly/diff_services_pb.rb
@@ -6,6 +6,8 @@ require 'diff_pb'
 
 module Gitaly
   module DiffService
+    # DiffService is a service which provides RPCs to inspect differences
+    # introduced between a set of commits.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/hook_services_pb.rb b/ruby/proto/gitaly/hook_services_pb.rb
index 4e444177c..6ecf549e9 100644
--- a/ruby/proto/gitaly/hook_services_pb.rb
+++ b/ruby/proto/gitaly/hook_services_pb.rb
@@ -6,6 +6,9 @@ require 'hook_pb'
 
 module Gitaly
   module HookService
+    # HookService is a service which provides the implementation of a subset of
+    # Git hooks. These are typically invoked via the `gitaly-hooks` binary to
+    # ensure that the actual hook logic is executed in the context of the server.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/namespace_services_pb.rb b/ruby/proto/gitaly/namespace_services_pb.rb
index 1d9fa6102..09174f063 100644
--- a/ruby/proto/gitaly/namespace_services_pb.rb
+++ b/ruby/proto/gitaly/namespace_services_pb.rb
@@ -6,6 +6,9 @@ require 'namespace_pb'
 
 module Gitaly
   module NamespaceService
+    # NamespaceService is a service which provides RPCs to manage namespaces of a
+    # storage. Namespaces had been used before Gitaly migrated to hashed storages
+    # and shouldn't be used nowadays anymore.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/objectpool_services_pb.rb b/ruby/proto/gitaly/objectpool_services_pb.rb
index 4f0f1c01c..5984af019 100644
--- a/ruby/proto/gitaly/objectpool_services_pb.rb
+++ b/ruby/proto/gitaly/objectpool_services_pb.rb
@@ -6,6 +6,10 @@ require 'objectpool_pb'
 
 module Gitaly
   module ObjectPoolService
+    # ObjectPoolService is a service containing RPCs to manipulate object pools.
+    # An object pool is a separate repository that can be linked to from multiple
+    # satellite repositories in order to deduplicate common objects between them.
+    # This is mostly used in the contexet of repository forks.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/praefect_services_pb.rb b/ruby/proto/gitaly/praefect_services_pb.rb
index 319feaaee..752bef266 100644
--- a/ruby/proto/gitaly/praefect_services_pb.rb
+++ b/ruby/proto/gitaly/praefect_services_pb.rb
@@ -6,6 +6,8 @@ require 'praefect_pb'
 
 module Gitaly
   module PraefectInfoService
+    # PraefectInfoService is a service which provides RPCs to query and modify
+    # Praefect-specific parameters.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/ref_services_pb.rb b/ruby/proto/gitaly/ref_services_pb.rb
index feab3e680..a508e3c7a 100644
--- a/ruby/proto/gitaly/ref_services_pb.rb
+++ b/ruby/proto/gitaly/ref_services_pb.rb
@@ -6,6 +6,7 @@ require 'ref_pb'
 
 module Gitaly
   module RefService
+    # RefService is a service that provides RPCs to list and modify Git references.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/remote_services_pb.rb b/ruby/proto/gitaly/remote_services_pb.rb
index 856f21cee..c8fce6ae1 100644
--- a/ruby/proto/gitaly/remote_services_pb.rb
+++ b/ruby/proto/gitaly/remote_services_pb.rb
@@ -6,6 +6,8 @@ require 'remote_pb'
 
 module Gitaly
   module RemoteService
+    # RemoteService is a service providing RPCs to interact with a remote
+    # repository that is hosted on another Git server.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/repository_services_pb.rb b/ruby/proto/gitaly/repository_services_pb.rb
index 3ff4a5acb..25f339ac2 100644
--- a/ruby/proto/gitaly/repository_services_pb.rb
+++ b/ruby/proto/gitaly/repository_services_pb.rb
@@ -6,6 +6,7 @@ require 'repository_pb'
 
 module Gitaly
   module RepositoryService
+    # RepositoryService is a service providing RPCs accessing repositories as a whole.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/server_services_pb.rb b/ruby/proto/gitaly/server_services_pb.rb
index 6c1711b2c..1d76e8667 100644
--- a/ruby/proto/gitaly/server_services_pb.rb
+++ b/ruby/proto/gitaly/server_services_pb.rb
@@ -6,6 +6,7 @@ require 'server_pb'
 
 module Gitaly
   module ServerService
+    # ServerService is a service that provides information about a Gitaly server.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/smarthttp_services_pb.rb b/ruby/proto/gitaly/smarthttp_services_pb.rb
index 256293a22..688d4e00f 100644
--- a/ruby/proto/gitaly/smarthttp_services_pb.rb
+++ b/ruby/proto/gitaly/smarthttp_services_pb.rb
@@ -6,6 +6,8 @@ require 'smarthttp_pb'
 
 module Gitaly
   module SmartHTTPService
+    # SmartHTTPService is a service that provides RPCs required for HTTP-based Git
+    # clones via the smart HTTP protocol.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/ssh_services_pb.rb b/ruby/proto/gitaly/ssh_services_pb.rb
index a50b0fa5a..d630bcb81 100644
--- a/ruby/proto/gitaly/ssh_services_pb.rb
+++ b/ruby/proto/gitaly/ssh_services_pb.rb
@@ -6,6 +6,7 @@ require 'ssh_pb'
 
 module Gitaly
   module SSHService
+    # SSHService is a service that provides RPCs required for SSH-based Git clones.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/transaction_services_pb.rb b/ruby/proto/gitaly/transaction_services_pb.rb
index 4e21fc2f6..58c8bfe40 100644
--- a/ruby/proto/gitaly/transaction_services_pb.rb
+++ b/ruby/proto/gitaly/transaction_services_pb.rb
@@ -6,6 +6,11 @@ require 'transaction_pb'
 
 module Gitaly
   module RefTransaction
+    # RefTransaction is a service which provides RPCs to interact with reference
+    # transactions. Reference transactions are used in the context of Gitaly
+    # Cluster to ensure that all nodes part of a single transaction perform the
+    # same change: given a set of changes, the changes are hashed and the hash is
+    # then voted on.
     class Service
 
       include ::GRPC::GenericService
diff --git a/ruby/proto/gitaly/wiki_services_pb.rb b/ruby/proto/gitaly/wiki_services_pb.rb
index 6e18e6893..2304ff3a7 100644
--- a/ruby/proto/gitaly/wiki_services_pb.rb
+++ b/ruby/proto/gitaly/wiki_services_pb.rb
@@ -6,6 +6,9 @@ require 'wiki_pb'
 
 module Gitaly
   module WikiService
+    # WikiService is a service that provides Wiki-related functionality. This
+    # service is deprecated and should not be used anymore. Instead, all
+    # functionality to implement Wikis should use Git-based RPCS.
     class Service
 
       include ::GRPC::GenericService