From 61399b7e2349cea0969e94c8c86501030e2d1066 Mon Sep 17 00:00:00 2001 From: Jean de Klerk Date: Fri, 11 May 2018 09:44:10 -0700 Subject: [PATCH 1/5] grpc: godoc improvements around ctx handling --- protoc-gen-go/grpc/grpc.go | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/protoc-gen-go/grpc/grpc.go b/protoc-gen-go/grpc/grpc.go index 1723680a8b..560a2f8dd4 100644 --- a/protoc-gen-go/grpc/grpc.go +++ b/protoc-gen-go/grpc/grpc.go @@ -160,8 +160,9 @@ func (g *grpc) generateService(file *generator.FileDescriptor, service *pb.Servi deprecated := service.GetOptions().GetDeprecated() g.P() - g.P("// Client API for ", servName, " service") - g.P() + g.P(fmt.Sprintf(`// Client API for %s service. +// +// For semantics around ctx use and closing/ending RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.`, servName)) // Client interface. if deprecated { From 5b370f268992078d6a88f7822357307aba28c92e Mon Sep 17 00:00:00 2001 From: Jean de Klerk Date: Fri, 11 May 2018 09:55:48 -0700 Subject: [PATCH 2/5] resolve review comments around streaming rpcs --- protoc-gen-go/grpc/grpc.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protoc-gen-go/grpc/grpc.go b/protoc-gen-go/grpc/grpc.go index 560a2f8dd4..406adcfad2 100644 --- a/protoc-gen-go/grpc/grpc.go +++ b/protoc-gen-go/grpc/grpc.go @@ -162,7 +162,7 @@ func (g *grpc) generateService(file *generator.FileDescriptor, service *pb.Servi g.P() g.P(fmt.Sprintf(`// Client API for %s service. // -// For semantics around ctx use and closing/ending RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.`, servName)) +// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.`, servName)) // Client interface. if deprecated { From 2519a24aec1eb5e289568d0ac16363e7a108a2f8 Mon Sep 17 00:00:00 2001 From: Jean de Klerk Date: Fri, 11 May 2018 11:35:44 -0700 Subject: [PATCH 3/5] regen protos --- protoc-gen-go/testdata/deprecated/deprecated.pb.go | 5 +++-- protoc-gen-go/testdata/grpc/grpc.pb.go | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/protoc-gen-go/testdata/deprecated/deprecated.pb.go b/protoc-gen-go/testdata/deprecated/deprecated.pb.go index 6ebae9da3a..d31a2e95b8 100644 --- a/protoc-gen-go/testdata/deprecated/deprecated.pb.go +++ b/protoc-gen-go/testdata/deprecated/deprecated.pb.go @@ -136,8 +136,9 @@ var _ grpc.ClientConn // is compatible with the grpc package it is being compiled against. const _ = grpc.SupportPackageIsVersion4 -// Client API for DeprecatedService service - +// Client API for DeprecatedService service. +// +// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. // Deprecated: Do not use. type DeprecatedServiceClient interface { // DeprecatedCall takes a DeprecatedRequest and returns a DeprecatedResponse. diff --git a/protoc-gen-go/testdata/grpc/grpc.pb.go b/protoc-gen-go/testdata/grpc/grpc.pb.go index 0bb4cbfd1b..ea212621db 100644 --- a/protoc-gen-go/testdata/grpc/grpc.pb.go +++ b/protoc-gen-go/testdata/grpc/grpc.pb.go @@ -158,8 +158,9 @@ var _ grpc.ClientConn // is compatible with the grpc package it is being compiled against. const _ = grpc.SupportPackageIsVersion4 -// Client API for Test service - +// Client API for Test service. +// +// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type TestClient interface { UnaryCall(ctx context.Context, in *SimpleRequest, opts ...grpc.CallOption) (*SimpleResponse, error) // This RPC streams from the server only. From 62951df2ce1c4b4b0bc0d31dde9e981d86090b42 Mon Sep 17 00:00:00 2001 From: Jean de Klerk Date: Fri, 11 May 2018 12:35:41 -0700 Subject: [PATCH 4/5] resolve joes comments around deprecation newline and godoc formatting --- protoc-gen-go/grpc/grpc.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/protoc-gen-go/grpc/grpc.go b/protoc-gen-go/grpc/grpc.go index 406adcfad2..b0a6fe3143 100644 --- a/protoc-gen-go/grpc/grpc.go +++ b/protoc-gen-go/grpc/grpc.go @@ -160,13 +160,13 @@ func (g *grpc) generateService(file *generator.FileDescriptor, service *pb.Servi deprecated := service.GetOptions().GetDeprecated() g.P() - g.P(fmt.Sprintf(`// Client API for %s service. + g.P(fmt.Sprintf(`// %sClient is the client API for %s service. // -// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.`, servName)) +// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.`, servName, servName)) // Client interface. if deprecated { - g.P(deprecationComment) + g.P("\n" + deprecationComment) } g.P("type ", servName, "Client interface {") for i, method := range service.Method { From fd7b4277a40e0110213d7bc0dce7fcecc671139e Mon Sep 17 00:00:00 2001 From: Jean de Klerk Date: Fri, 11 May 2018 13:25:41 -0700 Subject: [PATCH 5/5] regenerate protos --- protoc-gen-go/testdata/deprecated/deprecated.pb.go | 3 ++- protoc-gen-go/testdata/grpc/grpc.pb.go | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/protoc-gen-go/testdata/deprecated/deprecated.pb.go b/protoc-gen-go/testdata/deprecated/deprecated.pb.go index d31a2e95b8..5875b7f874 100644 --- a/protoc-gen-go/testdata/deprecated/deprecated.pb.go +++ b/protoc-gen-go/testdata/deprecated/deprecated.pb.go @@ -136,9 +136,10 @@ var _ grpc.ClientConn // is compatible with the grpc package it is being compiled against. const _ = grpc.SupportPackageIsVersion4 -// Client API for DeprecatedService service. +// DeprecatedServiceClient is the client API for DeprecatedService service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. + // Deprecated: Do not use. type DeprecatedServiceClient interface { // DeprecatedCall takes a DeprecatedRequest and returns a DeprecatedResponse. diff --git a/protoc-gen-go/testdata/grpc/grpc.pb.go b/protoc-gen-go/testdata/grpc/grpc.pb.go index ea212621db..6afe3a95e9 100644 --- a/protoc-gen-go/testdata/grpc/grpc.pb.go +++ b/protoc-gen-go/testdata/grpc/grpc.pb.go @@ -158,7 +158,7 @@ var _ grpc.ClientConn // is compatible with the grpc package it is being compiled against. const _ = grpc.SupportPackageIsVersion4 -// Client API for Test service. +// TestClient is the client API for Test service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type TestClient interface {