generated-code: update to include stream generics #1365

eshitachandwani · 2024-09-25T13:43:13Z

Fixes task 3 : grpc-go issue #1894 - update the grpc.io docs to use generics instead of generated interfaces.

eshitachandwani · 2024-10-01T09:30:06Z

Cannot add reviewer, @purnesh42H please review

murgatroid99 · 2024-10-01T22:45:46Z

@ejona86 can you take a look at this?

purnesh42H

lgtm

purnesh42H

Might be good to cross check here if we need to edit/add anything as we recently updated this https://github.com/grpc/grpc-go/blob/00b9e140ce71480ee7ecc6b85317021e0fe11fbb/stream_interfaces.go#L21

purnesh42H · 2024-10-10T08:45:01Z

content/en/docs/languages/go/generated-code.md

-messages from the client. `Recv` returns `(nil, io.EOF)` once it has reached the end of the stream.
-The single response message from the server is sent by calling the `SendAndClose` method on this `<ServiceName>_FooServer` parameter.
-Note that `SendAndClose` must be called once and only once.
+The `grpc.ClientStreamingServer` has two methods `Recv()` and `SendAndClose(*MsgB)` , has an embedded `ServerStream`. The server-side handler can repeatedly call `Recv` on `<ServiceName>_FooServer`  in order to receive the full stream of messages from the client. `Recv` returns `(nil, io.EOF)` once it has reached the end of the stream. The single response message from the server is sent by calling the `SendAndClose` method on this `<ServiceName>_FooServer` parameter. Note that `SendAndClose` must be called once and only once.


SendAndClose(*MsgB) , -> SendAndClose(*MsgB),

purnesh42H · 2024-10-10T08:46:48Z

content/en/docs/languages/go/generated-code.md


-In this context, `<ServiceName>_FooClient` represents the server-to-client `stream` of `MsgB` messages.
+In this context, `grpc.ServerStreamClient`  represents the client side of server-to-client stream of `MsgB` messages.


looks like there is extra space after grpc.ServerStreamClient

dfawley

Please apply the comments throughout, and please review your changes for correctness in light of all the typos. Thanks!

dfawley · 2024-10-14T15:56:59Z

content/en/docs/languages/go/generated-code.md


-`Foo(*MsgA, <ServiceName>_FooServer) error`
+In this context, `MsgA` is the single request from the client, and , and `grpc.ServerStreamingServer` represents the  server side of server-to-client stream of response type `MsgB`.


Also an extra space in the server side

dfawley · 2024-10-14T15:57:14Z

content/en/docs/languages/go/generated-code.md

-of `MsgB` messages.
-
-`<ServiceName>_FooServer` has an embedded `grpc.ServerStream` and the following interface:
+`<ServiceName>_FooServer` has a  `grpc.SreverStreamingServer` interface that takes `MsgB` i.e. the response type as the input:


Srever -> Server

dfawley · 2024-10-14T15:57:52Z

content/en/docs/languages/go/generated-code.md

-of `MsgB` messages.
-
-`<ServiceName>_FooServer` has an embedded `grpc.ServerStream` and the following interface:
+`<ServiceName>_FooServer` has a  `grpc.SreverStreamingServer` interface that takes `MsgB` i.e. the response type as the input:


Grammar: please use commas:

MsgB, i.e. the response type, as the input.

dfawley · 2024-10-14T15:58:10Z

content/en/docs/languages/go/generated-code.md

 ```

-The server-side handler can send a stream of protobuf messages to the client through this parameter's `Send` method. End-of-stream for the server-to-client
-stream is caused by the `return` of the handler method.
+The `grpc.SreverStreamingServer` has a `Send(*MsgB)` method and has `ServerStream` embedded in it.


dfawley · 2024-10-14T15:58:54Z

content/en/docs/languages/go/generated-code.md

-	Send(*MsgB) error
-	grpc.ServerStream
-}
+type <ServiceName>_FooServer = grpc.ServerStreamingServer[*MsgB]


Let's put documentation for the ServerStreamingServer here instead and leave out this leftover type alias, which is only there for backward compatibility. We can probably rely heavily on the existing documentation, or maybe even just link it: https://pkg.go.dev/google.golang.org/grpc#ServerStreamingServer

Delete this?

dfawley · 2024-10-14T16:01:16Z

content/en/docs/languages/go/generated-code.md


-`<ServiceName>_FooClient` has an embedded `grpc.ClientStream` and the following interface:
+`<ServiceName>_FooServe`r has a `grpc.ClientStreamingClient` interface that takes `MsgA` and `MsgB` as input:


dfawley · 2024-10-15T15:52:07Z

content/en/docs/languages/go/generated-code.md

-	Send(*MsgB) error
-	grpc.ServerStream
-}
+type <ServiceName>_FooServer = grpc.ServerStreamingServer[*MsgB]


Delete this?

dfawley · 2024-10-15T15:52:53Z

content/en/docs/languages/go/generated-code.md

-of `MsgB` messages.
-
-`<ServiceName>_FooServer` has an embedded `grpc.ServerStream` and the following interface:
+`<ServiceName>_FooServer` has a `grpc.ServerStreamingServer` interface that takes `MsgB`, i.e. the response type, as the input.


I think we shouldn't mention <ServiceName>_FooServer, since that name is no longer part of the generated code, except for backward compatibility.

But I wonder if we should have two documents, and link between them: one for the old generated code and one for the new generated code. So we can keep the old code for people that are working with an old generated file.

dfawley · 2024-10-21T20:06:58Z

content/en/docs/languages/go/generated-code.md

+This describes the code generated with the [grpc plugin](https://pkg.go.dev/google.golang.org/grpc/cmd/protoc-gen-go-grpc), `protoc-gen-go-grpc`,
+when compiling `.proto` files with `protoc` without the generics.
+
+
 ## Methods on generated server interfaces


Can we move the old documentation into another page and link to it from the top of this page? Just a little note like "The following documents the latest generated code guide which uses generics. For documentation about the older version of generated code that did not use generics, please see <this document>."?

dfawley · 2024-10-25T15:39:59Z

content/en/docs/languages/go/generated-code.md

@@ -34,68 +35,29 @@ In this context, `MsgA` is the protobuf message sent from the client, and `MsgB`
 ### Server-streaming methods

 These methods have the following signature on the generated service interface:
+`Foo(*MsgA, grpc.ServerStreamingServer[*MsgB]) error`


I think it would help to rename these from MsgA and MsgB to RequestMsg and ResponseMsg. WDYT?

Sounds good to me.

Changed in the new doc, did not change in the documentation for old generated code for continuity of users who might have been referring to it. Or should it be changed in the old documentation too.

dfawley · 2024-10-25T15:42:56Z

content/en/docs/languages/go/generated-code.md

-}
-```
-
-The server-side handler can send a stream of protobuf messages to the client through this parameter's `Send` method. End-of-stream for the server-to-client


Since all this documentation was deleted, let's explicitly call out that instructions on how to use the Stream type can be found at the pkg.go.dev link above.

dfawley · 2024-10-25T15:44:22Z

content/en/docs/languages/go/generated-code.md

+The following documents the latest generated code guide which uses generics.  For documentation about the older version of generated code that did not use generics, please see the doc for [old generated code](/docs/languages/go/generated-code-old).

 This page describes the code generated with the [grpc plugin](https://pkg.go.dev/google.golang.org/grpc/cmd/protoc-gen-go-grpc), `protoc-gen-go-grpc`,


Let's reverse the order of these two paragraphs, combine them into one, and make them flow better.

dfawley · 2024-10-25T15:45:49Z

content/en/docs/languages/go/generated-code.md

@@ -3,6 +3,7 @@ title: Generated-code reference
 linkTitle: Generated code
 weight: 95
 ---
+The following documents the latest generated code guide which uses generics.  For documentation about the older version of generated code that did not use generics, please see the doc for [old generated code](/docs/languages/go/generated-code-old).


Call out that this version of the generated code is the default, and that the old documentation is available for people who are looking at old generated code, and that it's temporarily possible to get this behavior by setting the flag.

dfawley · 2024-10-25T15:48:01Z

content/en/docs/languages/go/generated-code-old.md

@@ -0,0 +1,189 @@
+---


Is this just a copy/paste of the old markdown file? If so I won't review the language at all.

Yes, it is an exact copy of the old markdown file.

dfawley · 2024-10-25T15:49:14Z

content/en/docs/languages/go/generated-code-old.md

@@ -0,0 +1,189 @@
+---
+title: Generated-code(non-generic) reference    


Please put spaces before opening parentheses in text.

Maybe call this "legacy" instead?

dfawley · 2024-11-07T16:10:47Z

content/en/docs/languages/go/generated-code.md

-
-This page describes the code generated with the [grpc plugin](https://pkg.go.dev/google.golang.org/grpc/cmd/protoc-gen-go-grpc), `protoc-gen-go-grpc`,
-when compiling `.proto` files with `protoc`.
+This page describes the code generated when compiling `.proto` files with `protoc`, using the `protoc-gen-go-grpc` [grpc plugin](https://pkg.go.dev/google.golang.org/grpc/cmd/protoc-gen-go-grpc). This latest version of generated code uses generics by default. If you're working with older generated code that doesn't use generics, you can find the relevant documentation [here](/docs/languages/go/generated-code-old).  While we encourage using this latest version with generics, you can temporarily revert to the old behavior by setting the `useGenericStreams` flag to `false`.


Please update the issue about removing this flag to include some notes that we need to update this documentation when the flag is removed.

dfawley · 2024-11-07T16:15:20Z

content/en/docs/languages/go/generated-code.md


 You can find out how to define a gRPC service in a `.proto` file in [Service definition](/docs/what-is-grpc/core-concepts/#service-definition).

+To implement streaming in gRPC, refer directly to the [ServerStream](https://pkg.go.dev/google.golang.org/grpc#ServerStream) and [ClientStream](https://pkg.go.dev/google.golang.org/grpc#ClientStream) documentation, which provides comprehensive instructions for effectively using these types in your service methods.


This links to the types that are embedded in the generic streaming types. Better documentation for using the generic streaming types is present on the generic streaming types themselves.

This doc should call out the documentation on those generic streaming types. The doc strings for the generic streaming types already reference ClientStream and ServerStream.

Updating the generated code docs

8c4d81d

purnesh42H approved these changes Oct 10, 2024

View reviewed changes

purnesh42H reviewed Oct 10, 2024

View reviewed changes

dfawley changed the title ~~genetared-code : updating to include stream generics~~ generated-code: update to include stream generics Oct 14, 2024

dfawley reviewed Oct 14, 2024

View reviewed changes

Fixing typos

1793fd7

dfawley reviewed Oct 15, 2024

View reviewed changes

eshitachandwani and others added 10 commits October 19, 2024 01:38

revive old generated code and link to stream interfaces

0cfb265

Update generated-code-old.md

1b9f4a8

update name

847a07a

Update generated-code-old.md

2d420d5

change name

24a49f5

add

b2431e8

add to index.md

67f5cf9

add non-generics below

e2c9d04

Update _index.md

528de35

Update generated-code.md

3f167f8

eshitachandwani requested review from dfawley and purnesh42H October 18, 2024 21:04

eshitachandwani added 2 commits October 19, 2024 02:37

Update generated-code.md

491f0c4

Update generated-code.md

4432bc1

dfawley reviewed Oct 21, 2024

View reviewed changes

eshitachandwani added 2 commits October 22, 2024 11:07

new page for old code

7977b22

delete old code from below

6e50016

eshitachandwani requested a review from dfawley October 22, 2024 06:01

dfawley reviewed Oct 25, 2024

View reviewed changes

eshitachandwani and others added 2 commits October 27, 2024 20:01

address comments

f2dd5e4

Update generated-code.md

1abb42f

eshitachandwani requested a review from dfawley November 2, 2024 09:52

dfawley reviewed Nov 7, 2024

View reviewed changes


		In this context, `<ServiceName>_FooClient` represents the server-to-client `stream` of `MsgB` messages.
		In this context, `grpc.ServerStreamClient` represents the client side of server-to-client stream of `MsgB` messages.


		`Foo(*MsgA, <ServiceName>_FooServer) error`
		In this context, `MsgA` is the single request from the client, and , and `grpc.ServerStreamingServer` represents the server side of server-to-client stream of response type `MsgB`.


		`<ServiceName>_FooClient` has an embedded `grpc.ClientStream` and the following interface:
		`<ServiceName>_FooServe`r has a `grpc.ClientStreamingClient` interface that takes `MsgA` and `MsgB` as input:

		The following documents the latest generated code guide which uses generics. For documentation about the older version of generated code that did not use generics, please see the doc for [old generated code](/docs/languages/go/generated-code-old).

		This page describes the code generated with the [grpc plugin](https://pkg.go.dev/google.golang.org/grpc/cmd/protoc-gen-go-grpc), `protoc-gen-go-grpc`,

		@@ -0,0 +1,189 @@
		---
		title: Generated-code(non-generic) reference


		You can find out how to define a gRPC service in a `.proto` file in [Service definition](/docs/what-is-grpc/core-concepts/#service-definition).

		To implement streaming in gRPC, refer directly to the [ServerStream](https://pkg.go.dev/google.golang.org/grpc#ServerStream) and [ClientStream](https://pkg.go.dev/google.golang.org/grpc#ClientStream) documentation, which provides comprehensive instructions for effectively using these types in your service methods.

generated-code: update to include stream generics #1365

Are you sure you want to change the base?

generated-code: update to include stream generics #1365

Conversation

eshitachandwani commented Sep 25, 2024 • edited by dfawley Loading

eshitachandwani commented Oct 1, 2024

murgatroid99 commented Oct 1, 2024

purnesh42H left a comment

Choose a reason for hiding this comment

purnesh42H left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dfawley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eshitachandwani commented Sep 25, 2024 •

edited by dfawley

Loading