maintner/maintnerd: improve API documentation

Rearrange the maintner API documentation, and reflect the guarantee of at least two Go releases on success. Updates golang/go#32606 Change-Id: I90d5017f280254cc6482e747ffc1534f8a51bc20 Reviewed-on: https://go-review.googlesource.com/c/build/+/182981 Run-TryBot: Alexander Rakoczy <[email protected]> TryBot-Result: Gobot Gobot <[email protected]> Reviewed-by: Dmitri Shuralyov <[email protected]>
golang · Jul 3, 2019 · a473c25 · a473c25
1 parent 54405f2
commit a473c25
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 15 deletions.
diff --git a/maintner/maintnerd/apipb/api.pb.go b/maintner/maintnerd/apipb/api.pb.go
diff --git a/maintner/maintnerd/apipb/api.proto b/maintner/maintnerd/apipb/api.proto
@@ -72,12 +72,9 @@ message MajorMinor {
   int32 minor = 2;
 }
 
-// By default, ListGoReleases returns only the latest patches
-// of releases that are considered supported per policy.
 message ListGoReleasesRequest {}
 
 message ListGoReleasesResponse {
-  // Releases are Go releases, sorted by version with latest first.
   repeated GoRelease releases = 1;
 }
 
@@ -106,8 +103,15 @@ service MaintnerService {
   // GoFindTryWork finds trybot work for the coordinator to build & test.
   rpc GoFindTryWork(GoFindTryWorkRequest) returns (GoFindTryWorkResponse);
 
-  // ListGoReleases lists Go releases. A release is considered to exist for
-  // each git tag named "goX", "goX.Y", or "goX.Y.Z", as long as it has a
-  // corresponding "release-branch.goX" or "release-branch.goX.Y" release branch.
+  // ListGoReleases lists Go releases sorted by version with latest first.
+  //
+  // A release is considered to exist for each git tag named "goX", "goX.Y", or
+  // "goX.Y.Z", as long as it has a corresponding "release-branch.goX" or
+  // "release-branch.goX.Y" release branch.
+  //
+  // ListGoReleases returns only the latest patch versions of releases which
+  // are considered supported per policy. For example, Go 1.12.6 and 1.11.11.
+  // The response is guaranteed to have two versions, otherwise an error
+  // is returned.
   rpc ListGoReleases(ListGoReleasesRequest) returns (ListGoReleasesResponse);
 }