grpc: add docs for generic stream interfaces

stream_interfaces.go

@@ -22,15 +22,35 @@ package grpc
 // request, many responses) RPC. It is generic over the type of the response
 // message. It is used in generated code.
 type ServerStreamingClient[Res any] interface {
+	// Recv receives the next response message from the server. The client may
+	// repeatedly call Recv to read messages from the response stream.  If
+	// io.EOF is returned, the stream has terminated with an OK status.  Any
+	// other error is compatible with the status package and indicates the
+	// RPC's status code and message.
 	Recv() (*Res, error)
+
+	// ClientStream is embedded to provide Context, Header, and Trailer
+	// functionality.  No other methods in the ClientStream should be called
+	// directly.
 	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.
+//
+// To terminate the response stream, return from the handler method and return
+// an error from the status package, or use nil to indicate an OK status code.
 type ServerStreamingServer[Res any] interface {
+	// Send sends a response message to the client.  The server handler may
+	// call Send multiple times to send multiple messages to the client.  An
+	// error is returned if the stream was terminated unexpectedly, and the
+	// handler method should return, as the stream is no longer usable.
 	Send(*Res) error
+
+	// ServerStream is embedded to provide Context, SetHeader, SendHeader, and
+	// SetTrailer functionality.  No other methods in the ServerStream should
+	// be called directly.
 	ServerStream
 }
 
@@ -39,18 +59,51 @@ type ServerStreamingServer[Res any] interface {
 // message stream and the type of the unary response message. It is used in
 // generated code.
 type ClientStreamingClient[Req any, Res any] interface {
+	// Send sends a request message to the server.  The client may call Send
+	// multiple times to send multiple messages to the server.  On error, Send
+	// aborts the stream.  If the error was generated by the client, the status
+	// is returned directly.  Otherwise, io.EOF is returned, and the status of
+	// the stream may be discovered using CloseAndRecv().
 	Send(*Req) error
+
+	// CloseAndRecv closes the request stream and waits for the server's
+	// response.  This method must be called once and only once after sending
+	// all request messages.  Any error returned is implemented by the status
+	// package.
 	CloseAndRecv() (*Res, error)
+
+	// ClientStream is embedded to provide Context, Header, and Trailer
+	// functionality.  No other methods in the ClientStream should be called
+	// directly.
 	ClientStream
 }
 
 // ClientStreamingServer represents the server side of a client-streaming (many
 // 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.
+//
+// To terminate the RPC, call SendAndClose and return nil from the method
+// handler or do not call SendAndClose and return an error from the status
+// package.
 type ClientStreamingServer[Req any, Res any] interface {
+	// Recv receives the next request message from the client.  The server may
+	// repeatedly call Recv to read messages from the request stream.  If
+	// io.EOF is returned, it indicates the client called CloseAndRecv on its
+	// ClientStreamingClient.  Any other error indicates the stream was
+	// terminated unexpectedly, and the handler method should return, as the
+	// stream is no longer usable.
 	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.  Recv should not be called after
+	// calling SendAndClose.
 	SendAndClose(*Res) error
+
+	// ServerStream is embedded to provide Context, SetHeader, SendHeader, and
+	// SetTrailer functionality.  No other methods in the ServerStream should
+	// be called directly.
 	ServerStream
 }
 
@@ -59,18 +112,51 @@ type ClientStreamingServer[Req any, Res any] interface {
 // request message stream and the type of the response message stream. It is
 // used in generated code.
 type BidiStreamingClient[Req any, Res any] interface {
+	// Send sends a request message to the server.  The client may call Send
+	// multiple times to send multiple messages to the server.  On error, Send
+	// aborts the stream.  If the error was generated by the client, the status
+	// is returned directly.  Otherwise, io.EOF is returned, and the status of
+	// the stream may be discovered using Recv().
 	Send(*Req) error
+
+	// Recv receives the next response message from the server. The client may
+	// repeatedly call Recv to read messages from the response stream.  If
+	// io.EOF is returned, the stream has terminated with an OK status.  Any
+	// other error is compatible with the status package and indicates the
+	// RPC's status code and message.
 	Recv() (*Res, error)
+
+	// ClientStream is embedded to provide Context, Header, Trailer, and
+	// CloseSend functionality.  No other methods in the ClientStream should be
+	// called directly.
 	ClientStream
 }
 
 // BidiStreamingServer represents the server side of a bidirectional-streaming
 // (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.
+//
+// To terminate the stream, return from the handler method and return
+// an error from the status package, or use nil to indicate an OK status code.
 type BidiStreamingServer[Req any, Res any] interface {
+	// Recv receives the next request message from the client.  The server may
+	// repeatedly call Recv to read messages from the request stream.  If
+	// io.EOF is returned, it indicates the client called CloseSend on its
+	// BidiStreamingClient.  Any other error indicates the stream was
+	// terminated unexpectedly, and the handler method should return, as the
+	// stream is no longer usable.
 	Recv() (*Req, error)
+
+	// Send sends a response message to the client.  The server handler may
+	// call Send multiple times to send multiple messages to the client.  An
+	// error is returned if the stream was terminated unexpectedly, and the
+	// handler method should return, as the stream is no longer usable.
 	Send(*Res) error
+
+	// ServerStream is embedded to provide Context, SetHeader, SendHeader, and
+	// SetTrailer functionality.  No other methods in the ServerStream should
+	// be called directly.
 	ServerStream
 }