proto: Add documentation for PaginationParams and PaginationCursor

The documentation for PaginationParams and PaginationCursor is not
consistent at this point. So let's make it consistent and also point to
the documentation for the messages themselves to centralize the
documenation.

6 files changed, 28 insertions, 40 deletions

diff --git a/proto/commit.proto b/proto/commit.proto
index 3c247c8f0..29bdc3825 100644
--- a/proto/commit.proto
+++ b/proto/commit.proto
@@ -220,9 +220,8 @@ message ListCommitsRequest {
   // Must not be empty.
   repeated string revisions = 2;
 
-  // pagination_params allows implementation of pagination. The page token is
-  // the last commit OID that was sent. It's expected to be the full object ID
-  // to guard against ambigious OIDs.
+  // pagination_params controls paging. Refer to PaginationParameter documentation for
+  // further info.
   PaginationParameter pagination_params = 3;
 
   // order is the order in which commits should be traversed. Please refer to
@@ -276,9 +275,8 @@ message ListAllCommitsRequest {
   // repository is the repository in which commits should be searched for.
   Repository repository = 1 [(target_repository)=true];
 
-  // pagination_params allows implementation of pagination. The page token is
-  // the last commit OID that was sent. It's expected to be the full object ID
-  // to guard against ambigious OIDs.
+  // pagination_params controls paging. Refer to PaginationParameter documentation for
+  // further info.
   PaginationParameter pagination_params = 2;
 }
 
@@ -475,8 +473,8 @@ message GetTreeEntriesRequest {
   bool recursive = 4;
   // sort defines the sorting parameter.
   SortBy sort = 5;
-  // pagination_params allows implementation of pagination. The page token is
-  // the path of the last tree object that was sent.
+  // pagination_params controls paging. Refer to PaginationParameter documentation for
+  // further info.
   PaginationParameter pagination_params = 6;
   // skip_flat_paths is an option to skip the expensive operation of populating flat paths.
   bool skip_flat_paths = 7;
@@ -487,7 +485,8 @@ message GetTreeEntriesRequest {
 message GetTreeEntriesResponse {
   // entries denotes a list of tree entries.
   repeated TreeEntry entries = 1;
-  // pagination_cursor is a cursor to implement paginated requests.
+  // pagination_cursor defines the offset for subsequent requests. Refer to PaginationCursor
+  // documentation for further info.
   PaginationCursor pagination_cursor = 2;
 }
 
diff --git a/proto/go/gitalypb/commit.pb.go b/proto/go/gitalypb/commit.pb.go
index 82c0e8435..44c7e997d 100644
--- a/proto/go/gitalypb/commit.pb.go
+++ b/proto/go/gitalypb/commit.pb.go
@@ -414,9 +414,8 @@ type ListCommitsRequest struct {
 	// the pseudo-revisions `--not` and `--all` as documented in git-rev-list(1).
 	// Must not be empty.
 	Revisions []string `protobuf:"bytes,2,rep,name=revisions,proto3" json:"revisions,omitempty"`
-	// pagination_params allows implementation of pagination. The page token is
-	// the last commit OID that was sent. It's expected to be the full object ID
-	// to guard against ambigious OIDs.
+	// pagination_params controls paging. Refer to PaginationParameter documentation for
+	// further info.
 	PaginationParams *PaginationParameter `protobuf:"bytes,3,opt,name=pagination_params,json=paginationParams,proto3" json:"pagination_params,omitempty"`
 	// order is the order in which commits should be traversed. Please refer to
 	// the enum's documentation for further information.
@@ -629,9 +628,8 @@ type ListAllCommitsRequest struct {
 
 	// repository is the repository in which commits should be searched for.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// pagination_params allows implementation of pagination. The page token is
-	// the last commit OID that was sent. It's expected to be the full object ID
-	// to guard against ambigious OIDs.
+	// pagination_params controls paging. Refer to PaginationParameter documentation for
+	// further info.
 	PaginationParams *PaginationParameter `protobuf:"bytes,2,opt,name=pagination_params,json=paginationParams,proto3" json:"pagination_params,omitempty"`
 }
 
@@ -1563,8 +1561,8 @@ type GetTreeEntriesRequest struct {
 	Recursive bool `protobuf:"varint,4,opt,name=recursive,proto3" json:"recursive,omitempty"`
 	// sort defines the sorting parameter.
 	Sort GetTreeEntriesRequest_SortBy `protobuf:"varint,5,opt,name=sort,proto3,enum=gitaly.GetTreeEntriesRequest_SortBy" json:"sort,omitempty"`
-	// pagination_params allows implementation of pagination. The page token is
-	// the path of the last tree object that was sent.
+	// pagination_params controls paging. Refer to PaginationParameter documentation for
+	// further info.
 	PaginationParams *PaginationParameter `protobuf:"bytes,6,opt,name=pagination_params,json=paginationParams,proto3" json:"pagination_params,omitempty"`
 	// skip_flat_paths is an option to skip the expensive operation of populating flat paths.
 	SkipFlatPaths bool `protobuf:"varint,7,opt,name=skip_flat_paths,json=skipFlatPaths,proto3" json:"skip_flat_paths,omitempty"`
@@ -1660,7 +1658,8 @@ type GetTreeEntriesResponse struct {
 
 	// entries denotes a list of tree entries.
 	Entries []*TreeEntry `protobuf:"bytes,1,rep,name=entries,proto3" json:"entries,omitempty"`
-	// pagination_cursor is a cursor to implement paginated requests.
+	// pagination_cursor defines the offset for subsequent requests. Refer to PaginationCursor
+	// documentation for further info.
 	PaginationCursor *PaginationCursor `protobuf:"bytes,2,opt,name=pagination_cursor,json=paginationCursor,proto3" json:"pagination_cursor,omitempty"`
 }
 
diff --git a/proto/go/gitalypb/ref.pb.go b/proto/go/gitalypb/ref.pb.go
index 9cb175c6b..498868230 100644
--- a/proto/go/gitalypb/ref.pb.go
+++ b/proto/go/gitalypb/ref.pb.go
@@ -361,11 +361,8 @@ type FindLocalBranchesRequest struct {
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
 	// sort_by ...
 	SortBy FindLocalBranchesRequest_SortBy `protobuf:"varint,2,opt,name=sort_by,json=sortBy,proto3,enum=gitaly.FindLocalBranchesRequest_SortBy" json:"sort_by,omitempty"`
-	// pagination_params is used for pagination of the objects.
-	// The page token is the branch name, with the `refs/heads/` prefix, for
-	// example "refs/heads/master". After the first branch name is encountered
-	// which lexicographically exceeds the page token, it will be the first result
-	// send as part of the response.
+	// pagination_params controls paging. Refer to PaginationParameter documentation for
+	// further info.
 	PaginationParams *PaginationParameter `protobuf:"bytes,3,opt,name=pagination_params,json=paginationParams,proto3" json:"pagination_params,omitempty"`
 }
 
@@ -777,10 +774,8 @@ type FindAllTagsRequest struct {
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
 	// sort_by allows to request tags in particular order.
 	SortBy *FindAllTagsRequest_SortBy `protobuf:"bytes,2,opt,name=sort_by,json=sortBy,proto3" json:"sort_by,omitempty"`
-	// pagination_paramsi is used for pagination of the objects.
-	// The page token is the tags name, with the `refs/tags/` prefix, for
-	// example "refs/tags/v1.0.0". When the tag name matches the page token,
-	// the tag following it will be the first result send as part of the response.
+	// pagination_params controls paging. Refer to PaginationParameter documentation for
+	// further info.
 	PaginationParams *PaginationParameter `protobuf:"bytes,3,opt,name=pagination_params,json=paginationParams,proto3" json:"pagination_params,omitempty"`
 }
 
diff --git a/proto/go/gitalypb/shared.pb.go b/proto/go/gitalypb/shared.pb.go
index cb8385f0a..3090af28e 100644
--- a/proto/go/gitalypb/shared.pb.go
+++ b/proto/go/gitalypb/shared.pb.go
@@ -1063,7 +1063,7 @@ func (x *ObjectPool) GetRepository() *Repository {
 	return nil
 }
 
-// PaginationParameter ...
+// PaginationParameter controls pagination within RPCs.
 type PaginationParameter struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
@@ -1130,7 +1130,7 @@ func (x *PaginationParameter) GetLimit() int32 {
 	return 0
 }
 
-// PaginationCursor ...
+// PaginationCursor defines the page token clients should use to fetch the next page.
 type PaginationCursor struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
diff --git a/proto/ref.proto b/proto/ref.proto
index 21041906e..bf6806781 100644
--- a/proto/ref.proto
+++ b/proto/ref.proto
@@ -178,11 +178,8 @@ message FindLocalBranchesRequest {
   Repository repository = 1 [(target_repository)=true];
   // sort_by ...
   SortBy sort_by = 2;
-  // pagination_params is used for pagination of the objects.
-  // The page token is the branch name, with the `refs/heads/` prefix, for
-  // example "refs/heads/master". After the first branch name is encountered
-  // which lexicographically exceeds the page token, it will be the first result
-  // send as part of the response.
+  // pagination_params controls paging. Refer to PaginationParameter documentation for
+  // further info.
   PaginationParameter pagination_params = 3;
 }
 
@@ -273,10 +270,8 @@ message FindAllTagsRequest {
   Repository repository = 1 [(target_repository)=true];
   // sort_by allows to request tags in particular order.
   SortBy sort_by = 2;
-  // pagination_paramsi is used for pagination of the objects.
-  // The page token is the tags name, with the `refs/tags/` prefix, for
-  // example "refs/tags/v1.0.0". When the tag name matches the page token,
-  // the tag following it will be the first result send as part of the response.
+  // pagination_params controls paging. Refer to PaginationParameter documentation for
+  // further info.
   PaginationParameter pagination_params = 3;
 }
 
diff --git a/proto/shared.proto b/proto/shared.proto
index 861fa7eb8..c8d172fb5 100644
--- a/proto/shared.proto
+++ b/proto/shared.proto
@@ -203,7 +203,7 @@ message ObjectPool {
   Repository repository = 1 [(gitaly.repository)=true];
 }
 
-// PaginationParameter ...
+// PaginationParameter controls pagination within RPCs.
 message PaginationParameter {
   // page_token instructs pagination to start sending results after the provided page
   // token appears. A page token allows for a generic pattern to uniquely
@@ -220,7 +220,7 @@ message PaginationParameter {
   int32 limit = 2;
 }
 
-// PaginationCursor ...
+// PaginationCursor defines the page token clients should use to fetch the next page.
 message PaginationCursor {
   // next_cursor is an opaque token provided to the caller to indicate what the caller
   // should present as a page_token to get subsequent results.