Merge pull request #246 from overmindtech/update-pagination-docs

Clarify docs

util.proto

@@ -12,26 +12,32 @@ syntax = "proto3";
 option go_package = "github.com/overmindtech/sdp-go;sdp";
 
 message PaginationRequest {
-  // The number of items to return in a single page. The minimum is 10 and the maximum is 100.
+  // The number of items to return in a single page. The minimum is 10 and the
+  // maximum is 100.
   int32 pageSize = 1;
 
-  // The page number to return. the first page is 1.
-  // if the page number is larger than the total number of pages, the last page is returned.
-  // if the page number is negative, the first page 1 is returned.
+  // The page number to return. the first page is 1. If the page number is
+  // larger than the total number of pages, the last page is returned. If the
+  // page number is negative, the first page 1 is returned.
   int32 page = 2;
 }
 
 message PaginationResponse {
   // The number of items in the current page
   int32 pageSize = 1;
 
-  // The total number of items available. Expensive to calculate https://www.cybertec-postgresql.com/en/pagination-problem-total-result-count/
+  // The total number of items available. Expensive to calculate
+  // https://www.cybertec-postgresql.com/en/pagination-problem-total-result-count/
   // this is done as a separate query
   int32 totalItems = 2;
 
-  // The current page number, NB if the user provided a negative page number, this will be 1, if the user provided a page number larger than the total number of pages, this will be the last page.
+  // The current page number, NB if the user provided a negative page number,
+  // this will be 1, if the user provided a page number larger than the total
+  // number of pages, this will be the last page. If there are no results at
+  // all, this will be 0.
   int32 page = 3;
 
   // The total number of pages available. based on the totalItems and pageSize.
+  // If there are no results this will be zero.
   int32 totalPages = 4;
 }