netty: Clarify max header list size configuration

core/src/main/java/io/grpc/internal/GrpcUtil.java

@@ -151,6 +151,7 @@ public final class GrpcUtil {
   /**
    * The default maximum size (in bytes) for inbound header/trailer.
    */
+  // Update documentation in public-facing Builders when changing this value.
   public static final int DEFAULT_MAX_HEADER_LIST_SIZE = 8192;
 
   public static final Splitter ACCEPT_ENCODING_SPLITTER = Splitter.on(',').trimResults();

netty/src/main/java/io/grpc/netty/NettyChannelBuilder.java

@@ -209,8 +209,10 @@ public final class NettyChannelBuilder
   }
 
   /**
-   * Sets the maximum size of header list allowed to be received on the channel. If not called,
-   * defaults to {@link GrpcUtil#DEFAULT_MAX_HEADER_LIST_SIZE}.
+   * Sets the maximum size of header list allowed to be received. This is cumulative size of the
+   * headers with some overhead, as defined for
+   * <a href="http://httpwg.org/specs/rfc7540.html#rfc.section.6.5.2">
+   * HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE</a>. The default is 8 KiB.
    */
   public NettyChannelBuilder maxHeaderListSize(int maxHeaderListSize) {
     checkArgument(maxHeaderListSize > 0, "maxHeaderListSize must be > 0");

netty/src/main/java/io/grpc/netty/NettyServerBuilder.java

@@ -227,8 +227,10 @@ public final class NettyServerBuilder extends AbstractServerImplBuilder<NettySer
   }
 
   /**
-   * Sets the maximum size of header list allowed to be received on the server. If not called,
-   * defaults to {@link GrpcUtil#DEFAULT_MAX_HEADER_LIST_SIZE}.
+   * Sets the maximum size of header list allowed to be received. This is cumulative size of the
+   * headers with some overhead, as defined for
+   * <a href="http://httpwg.org/specs/rfc7540.html#rfc.section.6.5.2">
+   * HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE</a>. The default is 8 KiB.
    */
   public NettyServerBuilder maxHeaderListSize(int maxHeaderListSize) {
     checkArgument(maxHeaderListSize > 0, "maxHeaderListSize must be > 0");