grpc: Document interactions between static flow control window options (#9096)

Fixes: #9090

Setting a static flow control window at either the stream or connection
level entirely disables BDP estimation across the channel. If a user
configures one without the other, the unspecified window falls back to
the HTTP/2 default of 64KB, which can cause a severe drop in throughput.
This PR documents these interactions to help users avoid this common
footgun.

RELEASE NOTES: N/A

Author: arjan-bal

dialoptions.go

@@ -227,6 +227,14 @@ func WithInitialConnWindowSize(s int32) DialOption {
 
 // WithStaticStreamWindowSize returns a DialOption which sets the initial
 // stream window size to the value provided and disables dynamic flow control.
+//
+// Note that this also disables dynamic flow control for the connection,
+// falling back to a default static connection-level window of 64KB. To
+// use a larger connection-level window, you must also use the
+// [WithStaticConnWindowSize] DialOption.
+//
+// Most users should not configure static flow control windows unless
+// operating in a memory-constrained environment.
 func WithStaticStreamWindowSize(s int32) DialOption {
 	return newFuncDialOption(func(o *dialOptions) {
 		o.copts.InitialWindowSize = s
@@ -237,6 +245,14 @@ func WithStaticStreamWindowSize(s int32) DialOption {
 // WithStaticConnWindowSize returns a DialOption which sets the initial
 // connection window size to the value provided and disables dynamic flow
 // control.
+//
+// Note that this also disables dynamic flow control for individual streams,
+// falling back to a default static connection-level window of 64KB. To
+// explicitly configure the stream-level window size, you must also use the
+// [WithStaticStreamWindowSize] DialOption.
+//
+// Most users should not configure static flow control windows unless
+// operating in a memory-constrained environment.
 func WithStaticConnWindowSize(s int32) DialOption {
 	return newFuncDialOption(func(o *dialOptions) {
 		o.copts.InitialConnWindowSize = s

server.go

@@ -300,6 +300,14 @@ func InitialConnWindowSize(s int32) ServerOption {
 // window size to the value provided and disables dynamic flow control.
 // The lower bound for window size is 64K and any value smaller than that
 // will be ignored.
+//
+// Note that this also disables dynamic flow control for the connection,
+// falling back to a default static connection-level window of 64KB. To
+// use a larger connection-level window, you must also use the
+// [StaticConnWindowSize] ServerOption.
+//
+// Most users should not configure static flow control windows unless
+// operating in a memory-constrained environment.
 func StaticStreamWindowSize(s int32) ServerOption {
 	return newFuncServerOption(func(o *serverOptions) {
 		o.initialWindowSize = s
@@ -311,6 +319,14 @@ func StaticStreamWindowSize(s int32) ServerOption {
 // window size to the value provided and disables dynamic flow control.
 // The lower bound for window size is 64K and any value smaller than that
 // will be ignored.
+//
+// Note that this also disables dynamic flow control for individual streams,
+// falling back to a default static connection-level window of 64KB. To
+// explicitly configure the stream-level window size, you must also use the
+// [StaticStreamWindowSize] ServerOption.
+//
+// Most users should not configure static flow control windows unless
+// operating in a memory-constrained environment.
 func StaticConnWindowSize(s int32) ServerOption {
 	return newFuncServerOption(func(o *serverOptions) {
 		o.initialConnWindowSize = s