grpc: document ctx closure best practices (#600)

protoc-gen-go/grpc/grpc.go

@@ -160,12 +160,13 @@ 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(`// %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, servName))
 
 	// Client interface.
 	if deprecated {
-		g.P(deprecationComment)
+		g.P("\n" + deprecationComment)
 	}
 	g.P("type ", servName, "Client interface {")
 	for i, method := range service.Method {

protoc-gen-go/testdata/deprecated/deprecated.pb.go

@@ -136,7 +136,9 @@ 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 {

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
-
+// 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 {
 	UnaryCall(ctx context.Context, in *SimpleRequest, opts ...grpc.CallOption) (*SimpleResponse, error)
 	// This RPC streams from the server only.