From 8121e8118e541ad5de22f134eba7cefafcc0b64a Mon Sep 17 00:00:00 2001
From: Eric Anderson <ejona@google.com>
Date: Mon, 31 Jul 2023 15:40:38 -0700
Subject: [PATCH] api: Link to gRFCs A8/A9 for keepalive and related settings

This is to give users a place to look to learn more.
---
 .../main/java/io/grpc/ManagedChannelBuilder.java   |  6 ++++++
 api/src/main/java/io/grpc/ServerBuilder.java       | 14 ++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/api/src/main/java/io/grpc/ManagedChannelBuilder.java b/api/src/main/java/io/grpc/ManagedChannelBuilder.java
index 9012d05409..fd09ac9b82 100644
--- a/api/src/main/java/io/grpc/ManagedChannelBuilder.java
+++ b/api/src/main/java/io/grpc/ManagedChannelBuilder.java
@@ -352,6 +352,8 @@ public abstract class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>
    * small of a value as necessary.
    *
    * @throws UnsupportedOperationException if unsupported
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A8-client-side-keepalive.md">gRFC A8
+   *     Client-side Keepalive</a>
    * @since 1.7.0
    */
   public T keepAliveTime(long keepAliveTime, TimeUnit timeUnit) {
@@ -366,6 +368,8 @@ public abstract class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>
    * <p>This value should be at least multiple times the RTT to allow for lost packets.
    *
    * @throws UnsupportedOperationException if unsupported
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A8-client-side-keepalive.md">gRFC A8
+   *     Client-side Keepalive</a>
    * @since 1.7.0
    */
   public T keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit) {
@@ -383,6 +387,8 @@ public abstract class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>
    *
    * @throws UnsupportedOperationException if unsupported
    * @see #keepAliveTime(long, TimeUnit)
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A8-client-side-keepalive.md">gRFC A8
+   *     Client-side Keepalive</a>
    * @since 1.7.0
    */
   public T keepAliveWithoutCalls(boolean enable) {
diff --git a/api/src/main/java/io/grpc/ServerBuilder.java b/api/src/main/java/io/grpc/ServerBuilder.java
index 2df644e61a..db7996327c 100644
--- a/api/src/main/java/io/grpc/ServerBuilder.java
+++ b/api/src/main/java/io/grpc/ServerBuilder.java
@@ -249,6 +249,8 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    *
    * @throws IllegalArgumentException if time is not positive
    * @throws UnsupportedOperationException if unsupported
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A9-server-side-conn-mgt.md">gRFC A9
+   *     Server-side Connection Management</a>
    * @since 1.47.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009")
@@ -265,6 +267,8 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    *
    * @throws IllegalArgumentException if timeout is not positive
    * @throws UnsupportedOperationException if unsupported
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A9-server-side-conn-mgt.md">gRFC A9
+   *     Server-side Connection Management</a>
    * @since 1.47.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009")
@@ -281,6 +285,8 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    *
    * @throws IllegalArgumentException if idle is not positive
    * @throws UnsupportedOperationException if unsupported
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A9-server-side-conn-mgt.md">gRFC A9
+   *     Server-side Connection Management</a>
    * @since 1.47.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009")
@@ -296,6 +302,8 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    *
    * @throws IllegalArgumentException if age is not positive
    * @throws UnsupportedOperationException if unsupported
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A9-server-side-conn-mgt.md">gRFC A9
+   *     Server-side Connection Management</a>
    * @since 1.47.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009")
@@ -312,6 +320,8 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    * @throws IllegalArgumentException if grace is negative
    * @throws UnsupportedOperationException if unsupported
    * @see #maxConnectionAge(long, TimeUnit)
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A9-server-side-conn-mgt.md">gRFC A9
+   *     Server-side Connection Management</a>
    * @since 1.47.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009")
@@ -333,6 +343,8 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    * @throws IllegalArgumentException if time is negative
    * @throws UnsupportedOperationException if unsupported
    * @see #permitKeepAliveWithoutCalls(boolean)
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A8-client-side-keepalive.md">gRFC A8
+   *     Client-side Keepalive</a>
    * @since 1.47.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009")
@@ -346,6 +358,8 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    *
    * @throws UnsupportedOperationException if unsupported
    * @see #permitKeepAliveTime(long, TimeUnit)
+   * @see <a href="https://github.com/grpc/proposal/blob/master/A8-client-side-keepalive.md">gRFC A8
+   *     Client-side Keepalive</a>
    * @since 1.47.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009")