From d30fd6adb2330f66a806effdec3a13d464d5a0ca Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Wed, 8 Apr 2020 19:24:41 +0100 Subject: [PATCH] Small improvements to tutorials/basic/go.md (#178) - Fix line wrapping - Standardize references to .proto files (no code formatting) - Add missing punctuation --- content/docs/tutorials/basic/go.md | 60 +++++++++++++++--------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/content/docs/tutorials/basic/go.md b/content/docs/tutorials/basic/go.md index 6e87ec8..c0001ad 100644 --- a/content/docs/tutorials/basic/go.md +++ b/content/docs/tutorials/basic/go.md @@ -13,13 +13,12 @@ By walking through this example you'll learn how to: - Generate server and client code using the protocol buffer compiler. - Use the Go gRPC API to write a simple client and server for your service. -It assumes that you have read the [Overview](/docs/) and are familiar -with [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). Note that the -example in this tutorial uses the proto3 version of the protocol buffers -language: you can find out more in the -[proto3 language -guide](https://developers.google.com/protocol-buffers/docs/proto3) and the [Go -generated code +It assumes that you have read the [Overview](/docs/) and are familiar with +[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). +Note that the example in this tutorial uses the proto3 version of the protocol +buffers language: you can find out more in the [proto3 language +guide](https://developers.google.com/protocol-buffers/docs/proto3) and the +[Go generated code guide](https://developers.google.com/protocol-buffers/docs/reference/go-generated). ### Why use gRPC? @@ -54,15 +53,16 @@ Then change your current directory to `grpc-go/examples/route_guide`: $ cd $GOPATH/src/google.golang.org/grpc/examples/route_guide ``` -You also should have the relevant tools installed to generate the server and client interface code - if you don't already, follow the setup instructions in [the Go quick start guide](/docs/quickstart/go/). - +You also should have the relevant tools installed to generate the server and +client interface code - if you don't already, follow the setup instructions in +[the Go quick start guide](/docs/quickstart/go/). ### Defining the service Our first step (as you'll know from the [Overview](/docs/)) is to define the gRPC *service* and the method *request* and *response* types using -[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). You can see the -complete .proto file in +[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). +You can see the complete .proto file in [`examples/route_guide/routeguide/route_guide.proto`](https://github.com/grpc/grpc-go/blob/master/examples/route_guide/routeguide/route_guide.proto). To define a service, you specify a named `service` in your .proto file: @@ -126,7 +126,7 @@ all of which are used in the `RouteGuide` service: rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} ``` -Our `.proto` file also contains protocol buffer message type definitions for all +Our .proto file also contains protocol buffer message type definitions for all the request and response types used in our service methods - for example, here's the `Point` message type: @@ -146,9 +146,9 @@ message Point { Next we need to generate the gRPC client and server interfaces from our .proto service definition. We do this using the protocol buffer compiler `protoc` with a special gRPC Go plugin. -This is similar to what we did in the [quickstart guide](/docs/quickstart/go/) +This is similar to what we did in the [quickstart guide](/docs/quickstart/go/). -From the `route_guide` example directory run: +From the `route_guide` example directory, run: ```sh protoc -I routeguide/ routeguide/route_guide.proto --go_out=plugins=grpc:routeguide @@ -188,7 +188,8 @@ Let's take a closer look at how it works. #### Implementing RouteGuide -As you can see, our server has a `routeGuideServer` struct type that implements the generated `RouteGuideServer` interface: +As you can see, our server has a `routeGuideServer` struct type that implements +the generated `RouteGuideServer` interface: ```go type routeGuideServer struct { @@ -273,14 +274,13 @@ to be sent on the wire. ##### Client-side streaming RPC -Now let's look at something a little more complicated: the client-side -streaming method `RecordRoute`, where we get a stream of `Point`s from the -client and return a single `RouteSummary` with information about their trip. As -you can see, this time the method doesn't have a request parameter at all. -Instead, it gets a `RouteGuide_RecordRouteServer` stream, which the server can -use to both read *and* write messages - it can receive client messages using -its `Recv()` method and return its single response using its `SendAndClose()` -method. +Now let's look at something a little more complicated: the client-side streaming +method `RecordRoute`, where we get a stream of `Point`s from the client and +return a single `RouteSummary` with information about their trip. As you can +see, this time the method doesn't have a request parameter at all. Instead, it +gets a `RouteGuide_RecordRouteServer` stream, which the server can use to both +read *and* write messages - it can receive client messages using its `Recv()` +method and return its single response using its `SendAndClose()` method. ```go func (s *routeGuideServer) RecordRoute(stream pb.RouteGuide_RecordRouteServer) error { @@ -315,13 +315,13 @@ func (s *routeGuideServer) RecordRoute(stream pb.RouteGuide_RecordRouteServer) e } ``` -In the method body we use the `RouteGuide_RecordRouteServer`'s `Recv()` method to -repeatedly read in our client's requests to a request object (in this case a -`Point`) until there are no more messages: the server needs to check the -error returned from `Read()` after each call. If this is `nil`, the stream is -still good and it can continue reading; if it's `io.EOF` the message stream has -ended and the server can return its `RouteSummary`. If it has any other value, -we return the error "as is" so that it'll be translated to an RPC status by the +In the method body we use the `RouteGuide_RecordRouteServer`'s `Recv()` method +to repeatedly read in our client's requests to a request object (in this case a +`Point`) until there are no more messages: the server needs to check the error +returned from `Read()` after each call. If this is `nil`, the stream is still +good and it can continue reading; if it's `io.EOF` the message stream has ended +and the server can return its `RouteSummary`. If it has any other value, we +return the error "as is" so that it'll be translated to an RPC status by the gRPC layer. ##### Bidirectional streaming RPC