From 4f6d19f8e2bc819f2702df7f6d337987657453f1 Mon Sep 17 00:00:00 2001 From: silves-xiang Date: Sun, 19 May 2024 02:03:23 +0800 Subject: [PATCH] Feat:copy service comment to interfaces --- channelz/grpc_channelz_v1/channelz_grpc.pb.go | 6 ++++ cmd/protoc-gen-go-grpc/grpc.go | 16 ++++++++++ examples/features/proto/echo/echo_grpc.pb.go | 4 +++ .../helloworld/helloworld_grpc.pb.go | 4 +++ .../routeguide/route_guide_grpc.pb.go | 4 +++ health/grpc_health_v1/health_grpc.pb.go | 8 +++++ interop/grpc_testing/test_grpc.pb.go | 32 +++++++++++++++++++ profiling/proto/service_grpc.pb.go | 6 ++++ 8 files changed, 80 insertions(+) diff --git a/channelz/grpc_channelz_v1/channelz_grpc.pb.go b/channelz/grpc_channelz_v1/channelz_grpc.pb.go index 6bb3e915a34f..5fa65ff9a34b 100644 --- a/channelz/grpc_channelz_v1/channelz_grpc.pb.go +++ b/channelz/grpc_channelz_v1/channelz_grpc.pb.go @@ -52,6 +52,9 @@ const ( // ChannelzClient is the client API for Channelz service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// Channelz is a service exposed by gRPC servers that provides detailed debug +// information. type ChannelzClient interface { // Gets all root channels (i.e. channels the application has directly // created). This does not include subchannels nor non-top level channels. @@ -151,6 +154,9 @@ func (c *channelzClient) GetSocket(ctx context.Context, in *GetSocketRequest, op // ChannelzServer is the server API for Channelz service. // All implementations should embed UnimplementedChannelzServer // for forward compatibility +// +// Channelz is a service exposed by gRPC servers that provides detailed debug +// information. type ChannelzServer interface { // Gets all root channels (i.e. channels the application has directly // created). This does not include subchannels nor non-top level channels. diff --git a/cmd/protoc-gen-go-grpc/grpc.go b/cmd/protoc-gen-go-grpc/grpc.go index ddda50dacd45..d22a0ea50033 100644 --- a/cmd/protoc-gen-go-grpc/grpc.go +++ b/cmd/protoc-gen-go-grpc/grpc.go @@ -187,6 +187,15 @@ func generateFileContent(gen *protogen.Plugin, file *protogen.File, g *protogen. } } +// Copy comments from proto file to _grpc.pb.go file. +func genServiceComments(g *protogen.GeneratedFile, service *protogen.Service) { + if service.Comments.Leading != "" { + // Add empty comment line to attach this service's comments to the godoc comments previously output for all services. + g.P("//") + g.P(strings.TrimSpace(service.Comments.Leading.String())) + } +} + func genService(gen *protogen.Plugin, file *protogen.File, g *protogen.GeneratedFile, service *protogen.Service) { // Full methods constants. helper.genFullMethods(g, service) @@ -198,6 +207,9 @@ func genService(gen *protogen.Plugin, file *protogen.File, g *protogen.Generated g.P("//") g.P("// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.") + // Copy comments from proto file. + genServiceComments(g, service) + if service.Desc.Options().(*descriptorpb.ServiceOptions).GetDeprecated() { g.P("//") g.P(deprecationComment) @@ -251,6 +263,10 @@ func genService(gen *protogen.Plugin, file *protogen.File, g *protogen.Generated g.P("// ", serverType, " is the server API for ", service.GoName, " service.") g.P("// All implementations ", mustOrShould, " embed Unimplemented", serverType) g.P("// for forward compatibility") + + // Copy comments from proto file. + genServiceComments(g, service) + if service.Desc.Options().(*descriptorpb.ServiceOptions).GetDeprecated() { g.P("//") g.P(deprecationComment) diff --git a/examples/features/proto/echo/echo_grpc.pb.go b/examples/features/proto/echo/echo_grpc.pb.go index 2dc60f5ccc82..c04d05784848 100644 --- a/examples/features/proto/echo/echo_grpc.pb.go +++ b/examples/features/proto/echo/echo_grpc.pb.go @@ -45,6 +45,8 @@ const ( // EchoClient is the client API for Echo service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// Echo is the echo service. type EchoClient interface { // UnaryEcho is unary echo. UnaryEcho(ctx context.Context, in *EchoRequest, opts ...grpc.CallOption) (*EchoResponse, error) @@ -122,6 +124,8 @@ type Echo_BidirectionalStreamingEchoClient = grpc.BidiStreamingClient[EchoReques // EchoServer is the server API for Echo service. // All implementations must embed UnimplementedEchoServer // for forward compatibility +// +// Echo is the echo service. type EchoServer interface { // UnaryEcho is unary echo. UnaryEcho(context.Context, *EchoRequest) (*EchoResponse, error) diff --git a/examples/helloworld/helloworld/helloworld_grpc.pb.go b/examples/helloworld/helloworld/helloworld_grpc.pb.go index 2583cb42dab7..21b376dcd42b 100644 --- a/examples/helloworld/helloworld/helloworld_grpc.pb.go +++ b/examples/helloworld/helloworld/helloworld_grpc.pb.go @@ -39,6 +39,8 @@ const ( // GreeterClient is the client API for Greeter service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// The greeting service definition. type GreeterClient interface { // Sends a greeting SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloReply, error) @@ -65,6 +67,8 @@ func (c *greeterClient) SayHello(ctx context.Context, in *HelloRequest, opts ... // GreeterServer is the server API for Greeter service. // All implementations must embed UnimplementedGreeterServer // for forward compatibility +// +// The greeting service definition. type GreeterServer interface { // Sends a greeting SayHello(context.Context, *HelloRequest) (*HelloReply, error) diff --git a/examples/route_guide/routeguide/route_guide_grpc.pb.go b/examples/route_guide/routeguide/route_guide_grpc.pb.go index c309079185ce..3dacdbdc53af 100644 --- a/examples/route_guide/routeguide/route_guide_grpc.pb.go +++ b/examples/route_guide/routeguide/route_guide_grpc.pb.go @@ -42,6 +42,8 @@ const ( // RouteGuideClient is the client API for RouteGuide service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// Interface exported by the server. type RouteGuideClient interface { // A simple RPC. // @@ -135,6 +137,8 @@ type RouteGuide_RouteChatClient = grpc.BidiStreamingClient[RouteNote, RouteNote] // RouteGuideServer is the server API for RouteGuide service. // All implementations must embed UnimplementedRouteGuideServer // for forward compatibility +// +// Interface exported by the server. type RouteGuideServer interface { // A simple RPC. // diff --git a/health/grpc_health_v1/health_grpc.pb.go b/health/grpc_health_v1/health_grpc.pb.go index 8f793e6e89f7..1518e32545e4 100644 --- a/health/grpc_health_v1/health_grpc.pb.go +++ b/health/grpc_health_v1/health_grpc.pb.go @@ -43,6 +43,10 @@ const ( // HealthClient is the client API for Health service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// Health is gRPC's mechanism for checking whether a server is able to handle +// RPCs. Its semantics are documented in +// https://github.com/grpc/grpc/blob/master/doc/health-checking.md. type HealthClient interface { // Check gets the health of the specified service. If the requested service // is unknown, the call will fail with status NOT_FOUND. If the caller does @@ -126,6 +130,10 @@ func (x *healthWatchClient) Recv() (*HealthCheckResponse, error) { // HealthServer is the server API for Health service. // All implementations should embed UnimplementedHealthServer // for forward compatibility +// +// Health is gRPC's mechanism for checking whether a server is able to handle +// RPCs. Its semantics are documented in +// https://github.com/grpc/grpc/blob/master/doc/health-checking.md. type HealthServer interface { // Check gets the health of the specified service. If the requested service // is unknown, the call will fail with status NOT_FOUND. If the caller does diff --git a/interop/grpc_testing/test_grpc.pb.go b/interop/grpc_testing/test_grpc.pb.go index f6ae2a4ae47d..4ae334be8325 100644 --- a/interop/grpc_testing/test_grpc.pb.go +++ b/interop/grpc_testing/test_grpc.pb.go @@ -49,6 +49,9 @@ const ( // TestServiceClient is the client API for TestService service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// A simple service to test the various types of RPCs and experiment with +// performance with various types of payload. type TestServiceClient interface { // One empty request followed by one empty response. EmptyCall(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*Empty, error) @@ -187,6 +190,9 @@ func (c *testServiceClient) UnimplementedCall(ctx context.Context, in *Empty, op // TestServiceServer is the server API for TestService service. // All implementations must embed UnimplementedTestServiceServer // for forward compatibility +// +// A simple service to test the various types of RPCs and experiment with +// performance with various types of payload. type TestServiceServer interface { // One empty request followed by one empty response. EmptyCall(context.Context, *Empty) (*Empty, error) @@ -420,6 +426,9 @@ const ( // UnimplementedServiceClient is the client API for UnimplementedService service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// A simple service NOT implemented at servers so clients can test for +// that case. type UnimplementedServiceClient interface { // A call that no server should implement UnimplementedCall(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*Empty, error) @@ -446,6 +455,9 @@ func (c *unimplementedServiceClient) UnimplementedCall(ctx context.Context, in * // UnimplementedServiceServer is the server API for UnimplementedService service. // All implementations must embed UnimplementedUnimplementedServiceServer // for forward compatibility +// +// A simple service NOT implemented at servers so clients can test for +// that case. type UnimplementedServiceServer interface { // A call that no server should implement UnimplementedCall(context.Context, *Empty) (*Empty, error) @@ -514,6 +526,8 @@ const ( // ReconnectServiceClient is the client API for ReconnectService service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// A service used to control reconnect server. type ReconnectServiceClient interface { Start(ctx context.Context, in *ReconnectParams, opts ...grpc.CallOption) (*Empty, error) Stop(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*ReconnectInfo, error) @@ -550,6 +564,8 @@ func (c *reconnectServiceClient) Stop(ctx context.Context, in *Empty, opts ...gr // ReconnectServiceServer is the server API for ReconnectService service. // All implementations must embed UnimplementedReconnectServiceServer // for forward compatibility +// +// A service used to control reconnect server. type ReconnectServiceServer interface { Start(context.Context, *ReconnectParams) (*Empty, error) Stop(context.Context, *Empty) (*ReconnectInfo, error) @@ -643,6 +659,8 @@ const ( // LoadBalancerStatsServiceClient is the client API for LoadBalancerStatsService service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// A service used to obtain stats for verifying LB behavior. type LoadBalancerStatsServiceClient interface { // Gets the backend distribution for RPCs sent by a test client. GetClientStats(ctx context.Context, in *LoadBalancerStatsRequest, opts ...grpc.CallOption) (*LoadBalancerStatsResponse, error) @@ -681,6 +699,8 @@ func (c *loadBalancerStatsServiceClient) GetClientAccumulatedStats(ctx context.C // LoadBalancerStatsServiceServer is the server API for LoadBalancerStatsService service. // All implementations must embed UnimplementedLoadBalancerStatsServiceServer // for forward compatibility +// +// A service used to obtain stats for verifying LB behavior. type LoadBalancerStatsServiceServer interface { // Gets the backend distribution for RPCs sent by a test client. GetClientStats(context.Context, *LoadBalancerStatsRequest) (*LoadBalancerStatsResponse, error) @@ -778,6 +798,8 @@ const ( // HookServiceClient is the client API for HookService service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// Hook service. Used to keep Kubernetes from shutting the pod down. type HookServiceClient interface { // Sends a request that will "hang" until the return status is set by a call // to a SetReturnStatus @@ -829,6 +851,8 @@ func (c *hookServiceClient) ClearReturnStatus(ctx context.Context, in *Empty, op // HookServiceServer is the server API for HookService service. // All implementations must embed UnimplementedHookServiceServer // for forward compatibility +// +// Hook service. Used to keep Kubernetes from shutting the pod down. type HookServiceServer interface { // Sends a request that will "hang" until the return status is set by a call // to a SetReturnStatus @@ -953,6 +977,8 @@ const ( // XdsUpdateHealthServiceClient is the client API for XdsUpdateHealthService service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// A service to remotely control health status of an xDS test server. type XdsUpdateHealthServiceClient interface { SetServing(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*Empty, error) SetNotServing(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*Empty, error) @@ -1000,6 +1026,8 @@ func (c *xdsUpdateHealthServiceClient) SendHookRequest(ctx context.Context, in * // XdsUpdateHealthServiceServer is the server API for XdsUpdateHealthService service. // All implementations must embed UnimplementedXdsUpdateHealthServiceServer // for forward compatibility +// +// A service to remotely control health status of an xDS test server. type XdsUpdateHealthServiceServer interface { SetServing(context.Context, *Empty) (*Empty, error) SetNotServing(context.Context, *Empty) (*Empty, error) @@ -1119,6 +1147,8 @@ const ( // XdsUpdateClientConfigureServiceClient is the client API for XdsUpdateClientConfigureService service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// A service to dynamically update the configuration of an xDS test client. type XdsUpdateClientConfigureServiceClient interface { // Update the tes client's configuration. Configure(ctx context.Context, in *ClientConfigureRequest, opts ...grpc.CallOption) (*ClientConfigureResponse, error) @@ -1145,6 +1175,8 @@ func (c *xdsUpdateClientConfigureServiceClient) Configure(ctx context.Context, i // XdsUpdateClientConfigureServiceServer is the server API for XdsUpdateClientConfigureService service. // All implementations must embed UnimplementedXdsUpdateClientConfigureServiceServer // for forward compatibility +// +// A service to dynamically update the configuration of an xDS test client. type XdsUpdateClientConfigureServiceServer interface { // Update the tes client's configuration. Configure(context.Context, *ClientConfigureRequest) (*ClientConfigureResponse, error) diff --git a/profiling/proto/service_grpc.pb.go b/profiling/proto/service_grpc.pb.go index efc4396d471f..5e96e5029654 100644 --- a/profiling/proto/service_grpc.pb.go +++ b/profiling/proto/service_grpc.pb.go @@ -40,6 +40,9 @@ const ( // ProfilingClient is the client API for Profiling service. // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// The Profiling service exposes functions to remotely manage the gRPC +// profiling behaviour in a program. type ProfilingClient interface { // Enable allows users to toggle profiling on and off remotely. Enable(ctx context.Context, in *EnableRequest, opts ...grpc.CallOption) (*EnableResponse, error) @@ -79,6 +82,9 @@ func (c *profilingClient) GetStreamStats(ctx context.Context, in *GetStreamStats // ProfilingServer is the server API for Profiling service. // All implementations should embed UnimplementedProfilingServer // for forward compatibility +// +// The Profiling service exposes functions to remotely manage the gRPC +// profiling behaviour in a program. type ProfilingServer interface { // Enable allows users to toggle profiling on and off remotely. Enable(context.Context, *EnableRequest) (*EnableResponse, error)