grpc: add docs for generic stream interfaces

stream_interfaces.go

@@ -21,15 +21,27 @@ package grpc
 // ServerStreamingClient represents the client side of a server-streaming (one
 // request, many responses) RPC. It is generic over the type of the response
 // message. It is used in generated code.
+//
+// The error returned will be compatible to the status package.
 type ServerStreamingClient[Res any] interface {
+	// Recv receives the next message from the server. The client can repeatedly
+	// call Recv to read messages from the server-to-client response stream.
+	// Recv returns (nil, io.EOF) once the server-to-client stream is completely
+	// read.
 	Recv() (*Res, error)
 	ClientStream
 }
 
 // ServerStreamingServer represents the server side of a server-streaming (one
 // request, many responses) RPC. It is generic over the type of the response
 // message. It is used in generated code.
+//
+// The error returned will be compatible to the status package.
+// End-of-stream for the server-to-client stream is indicated by the return
+// of the handler method.
 type ServerStreamingServer[Res any] interface {
+	// Send can send a stream of messages to the client. Server handler may call
+	// Send multiple times to send multiple messages to the client.
 	Send(*Res) error
 	ServerStream
 }
@@ -38,8 +50,17 @@ type ServerStreamingServer[Res any] interface {
 // requests, one response) RPC. It is generic over both the type of the request
 // message stream and the type of the unary response message. It is used in
 // generated code.
+//
+// The error returned will be compatible to the status package.
 type ClientStreamingClient[Req any, Res any] interface {
+	// Send sends a request message to the server. The client can repeatedly
+	// call Send to send messages as part of the client-to-server request stream.
 	Send(*Req) error
+
+	// CloseAndRecv closes the client-to-server request stream and waits for the
+	// server's unary response. This method must be called once and only once
+	// after sending all request messages to close the stream and receive the
+	// final response from the server.
 	CloseAndRecv() (*Res, error)
 	ClientStream
 }
@@ -48,8 +69,18 @@ type ClientStreamingClient[Req any, Res any] interface {
 // requests, one response) RPC. It is generic over both the type of the request
 // message stream and the type of the unary response message. It is used in
 // generated code.
+//
+// The error returned will be compatible to the status package.
 type ClientStreamingServer[Req any, Res any] interface {
+	// Recv reads a request message from the client. This method can be called
+	// repeatedly to receive the full stream of messages from the client. Recv
+	// returns (nil, io.EOF) once the end of the stream is reached.
 	Recv() (*Req, error)
+
+	// SendAndClose sends a single response message to the client and closes the
+	// stream. This method must be called once and only once after all request
+	// messages have been processed. No further methods should be called after
+	// SendAndClose.
 	SendAndClose(*Res) error
 	ServerStream
 }
@@ -58,8 +89,19 @@ type ClientStreamingServer[Req any, Res any] interface {
 // (many requests, many responses) RPC. It is generic over both the type of the
 // request message stream and the type of the response message stream. It is
 // used in generated code.
+//
+// The error returned will be compatible to the status package.
+// End-of-stream for the client-to-server stream can be indicated by calling
+// the CloseSend method.
 type BidiStreamingClient[Req any, Res any] interface {
+	// Send sends a message to the server. This method can be called repeatedly
+	// to send messages as part of the client-to-server request stream.
 	Send(*Req) error
+
+	// Recv receives the next message from the server's response stream. This
+	// method can be called repeatedly to receive all messages sent by the
+	// server. Recv returns (nil, io.EOF) once the server-to-client stream is
+	// completely read.
 	Recv() (*Res, error)
 	ClientStream
 }
@@ -68,8 +110,18 @@ type BidiStreamingClient[Req any, Res any] interface {
 // (many requests, many responses) RPC. It is generic over both the type of the
 // request message stream and the type of the response message stream. It is
 // used in generated code.
+//
+// The error returned will be compatible to the status package.
+// The end of the response stream is indicated by the return of the bidi
+// method handler.
 type BidiStreamingServer[Req any, Res any] interface {
+	// Recv receives a request message from the client. The server-side handler
+	// can repeatedly call Recv to read the request message stream. Recv returns
+	// (nil, io.EOF) once the end of the client-to-server stream is reached.
 	Recv() (*Req, error)
+
+	// Send sends a response message to the client. The server-side handler can
+	// repeatedly call Send to write to the server-to-client message stream.
 	Send(*Res) error
 	ServerStream
 }