From 9fc12e8e694c0c7260574262348749dd984f738f Mon Sep 17 00:00:00 2001 From: Mira Leung Date: Fri, 4 Sep 2020 15:07:47 -0700 Subject: [PATCH] [ggj][codegen] feat: add comments for GrpcServiceCallableFactory, GrpcServiceStub, ServiceStub (#276) * feat: parse batching descriptor fields * feat: add Field.isMap and map-parsing test * feat: add initial batching descriptor field to ServiceStubSettings * feat: support '? extends Foo' wildcard bounded references * fix: speed up precommit checks with --disk_cache * feat: add splitException, count{Elements,Bytes} batching descriptor methods to ServiceStubSettings * feat: add GeneralForStatement * feat: add splitRseponse to batching desc. in ServiceStubSettings * fix: output srcjar path * feat: add method comments to ServiceStubSettings, fix AST formatting * feat: add class Javadoc to ServiceStubSettings * feat: add class Javadoc to ServiceStubSettings * feat: add comments to ServiceSettings * fix: file move * feat: add comments for GrpcServiceCallableFactory, GrpcServiceStub, ServiceStub --- ...pcServiceCallableFactoryClassComposer.java | 3 + .../GrpcServiceStubClassComposer.java | 2 + .../composer/ServiceStubClassComposer.java | 2 + .../gapic/composer/StubComentComposer.java | 65 +++++++++++++++++++ ...rviceCallableFactoryClassComposerTest.java | 6 ++ .../GrpcServiceStubClassComposerTest.java | 6 ++ .../ServiceStubClassComposerTest.java | 6 ++ 7 files changed, 90 insertions(+) create mode 100644 src/main/java/com/google/api/generator/gapic/composer/StubComentComposer.java diff --git a/src/main/java/com/google/api/generator/gapic/composer/GrpcServiceCallableFactoryClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/GrpcServiceCallableFactoryClassComposer.java index 8263b17312..5d1f054e2f 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/GrpcServiceCallableFactoryClassComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/GrpcServiceCallableFactoryClassComposer.java @@ -73,6 +73,9 @@ public GapicClass generate(Service service, Map ignore) { ClassDefinition classDef = ClassDefinition.builder() .setPackageString(pakkage) + .setHeaderCommentStatements( + StubCommentComposer.createGrpcServiceCallableFactoryClassHeaderComments( + service.name())) .setAnnotations(createClassAnnotations(types)) .setImplementsTypes(createClassImplements(types)) .setName(className) diff --git a/src/main/java/com/google/api/generator/gapic/composer/GrpcServiceStubClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/GrpcServiceStubClassComposer.java index 5d47bbe9b3..8b7eb4f31e 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/GrpcServiceStubClassComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/GrpcServiceStubClassComposer.java @@ -140,6 +140,8 @@ public GapicClass generate(Service service, Map ignore) { ClassDefinition classDef = ClassDefinition.builder() .setPackageString(pakkage) + .setHeaderCommentStatements( + StubCommentComposer.createGrpcServiceStubClassHeaderComments(service.name())) .setAnnotations(createClassAnnotations()) .setScope(ScopeNode.PUBLIC) .setName(className) diff --git a/src/main/java/com/google/api/generator/gapic/composer/ServiceStubClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/ServiceStubClassComposer.java index f2998431ae..cf849c947b 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/ServiceStubClassComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/ServiceStubClassComposer.java @@ -65,6 +65,8 @@ public GapicClass generate(Service service, Map messageTypes) { ClassDefinition classDef = ClassDefinition.builder() .setPackageString(pakkage) + .setHeaderCommentStatements( + StubCommentComposer.createServiceStubClassHeaderComments(service.name())) .setAnnotations(createClassAnnotations(types)) .setIsAbstract(true) .setImplementsTypes(createClassImplements(types)) diff --git a/src/main/java/com/google/api/generator/gapic/composer/StubComentComposer.java b/src/main/java/com/google/api/generator/gapic/composer/StubComentComposer.java new file mode 100644 index 0000000000..fb7731496d --- /dev/null +++ b/src/main/java/com/google/api/generator/gapic/composer/StubComentComposer.java @@ -0,0 +1,65 @@ +// Copyright 2020 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package com.google.api.generator.gapic.composer; + +import com.google.api.generator.engine.ast.CommentStatement; +import com.google.api.generator.engine.ast.JavaDocComment; +import java.util.Arrays; +import java.util.List; + +class StubCommentComposer { + private static final String STUB_CLASS_HEADER_SUMMARY_PATTERN = + "Base stub class for the %s service API."; + private static final String GRPC_CALLABLE_FACTORY_CLASS_HEADER_SUMMARY_PATTERN = + "gRPC callable factory implementation for the %s service API."; + private static final String GRPC_STUB_CLASS_HEADER_SUMMARY_PATTERN = + "gRPC stub implementation for the %s service API."; + + private static final String ADVANCED_USAGE_DESCRIPTION = "This class is for advanced usage."; + private static final String ADVANCED_USAGE_API_REFLECTION_DESCRIPTION = + "This class is for advanced usage and reflects the underlying API directly."; + + static List createGrpcServiceStubClassHeaderComments(String serviceName) { + return Arrays.asList( + CommentComposer.AUTO_GENERATED_CLASS_COMMENT, + CommentStatement.withComment( + JavaDocComment.builder() + .addComment(String.format(GRPC_STUB_CLASS_HEADER_SUMMARY_PATTERN, serviceName)) + .addParagraph(ADVANCED_USAGE_API_REFLECTION_DESCRIPTION) + .build())); + } + + static List createGrpcServiceCallableFactoryClassHeaderComments( + String serviceName) { + return Arrays.asList( + CommentComposer.AUTO_GENERATED_CLASS_COMMENT, + CommentStatement.withComment( + JavaDocComment.builder() + .addComment( + String.format(GRPC_CALLABLE_FACTORY_CLASS_HEADER_SUMMARY_PATTERN, serviceName)) + .addParagraph(ADVANCED_USAGE_DESCRIPTION) + .build())); + } + + static List createServiceStubClassHeaderComments(String serviceName) { + return Arrays.asList( + CommentComposer.AUTO_GENERATED_CLASS_COMMENT, + CommentStatement.withComment( + JavaDocComment.builder() + .addComment(String.format(STUB_CLASS_HEADER_SUMMARY_PATTERN, serviceName)) + .addParagraph(ADVANCED_USAGE_API_REFLECTION_DESCRIPTION) + .build())); + } +} diff --git a/src/test/java/com/google/api/generator/gapic/composer/GrpcServiceCallableFactoryClassComposerTest.java b/src/test/java/com/google/api/generator/gapic/composer/GrpcServiceCallableFactoryClassComposerTest.java index c935ceca41..33bb12caad 100644 --- a/src/test/java/com/google/api/generator/gapic/composer/GrpcServiceCallableFactoryClassComposerTest.java +++ b/src/test/java/com/google/api/generator/gapic/composer/GrpcServiceCallableFactoryClassComposerTest.java @@ -83,6 +83,12 @@ public void generateServiceClasses() { + "import com.google.longrunning.stub.OperationsStub;\n" + "import javax.annotation.Generated;\n" + "\n" + + "// AUTO-GENERATED DOCUMENTATION AND CLASS.\n" + + "/**\n" + + " * gRPC callable factory implementation for the Echo service API.\n" + + " *\n" + + " *

This class is for advanced usage.\n" + + " */\n" + "@Generated(\"by gapic-generator\")\n" + "public class GrpcEchoCallableFactory implements GrpcStubCallableFactory {\n" + "\n" diff --git a/src/test/java/com/google/api/generator/gapic/composer/GrpcServiceStubClassComposerTest.java b/src/test/java/com/google/api/generator/gapic/composer/GrpcServiceStubClassComposerTest.java index 81b04fbba5..9bd357bc15 100644 --- a/src/test/java/com/google/api/generator/gapic/composer/GrpcServiceStubClassComposerTest.java +++ b/src/test/java/com/google/api/generator/gapic/composer/GrpcServiceStubClassComposerTest.java @@ -93,6 +93,12 @@ public void generateServiceClasses() { + "import java.util.concurrent.TimeUnit;\n" + "import javax.annotation.Generated;\n" + "\n" + + "// AUTO-GENERATED DOCUMENTATION AND CLASS.\n" + + "/**\n" + + " * gRPC stub implementation for the Echo service API.\n" + + " *\n" + + " *

This class is for advanced usage and reflects the underlying API directly.\n" + + " */\n" + "@Generated(\"by gapic-generator-java\")\n" + "public class GrpcEchoStub extends EchoStub {\n" + " private static final MethodDescriptor" diff --git a/src/test/java/com/google/api/generator/gapic/composer/ServiceStubClassComposerTest.java b/src/test/java/com/google/api/generator/gapic/composer/ServiceStubClassComposerTest.java index 54d9ef5051..8ce0fac92c 100644 --- a/src/test/java/com/google/api/generator/gapic/composer/ServiceStubClassComposerTest.java +++ b/src/test/java/com/google/api/generator/gapic/composer/ServiceStubClassComposerTest.java @@ -82,6 +82,12 @@ public void generateServiceClasses() { + "import com.google.showcase.v1beta1.WaitResponse;\n" + "import javax.annotation.Generated;\n" + "\n" + + "// AUTO-GENERATED DOCUMENTATION AND CLASS.\n" + + "/**\n" + + " * Base stub class for the Echo service API.\n" + + " *\n" + + " *

This class is for advanced usage and reflects the underlying API directly.\n" + + " */\n" + "@Generated(\"by gapic-generator\")\n" + "public abstract class EchoStub implements BackgroundResource {\n" + "\n"