[ggj][codegen] feat: add comments for GrpcServiceCallableFactory, Grp…

…cServiceStub, 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

src/main/java/com/google/api/generator/gapic/composer/GrpcServiceCallableFactoryClassComposer.java

@@ -73,6 +73,9 @@ public GapicClass generate(Service service, Map<String, Message> ignore) {
     ClassDefinition classDef =
         ClassDefinition.builder()
             .setPackageString(pakkage)
+            .setHeaderCommentStatements(
+                StubCommentComposer.createGrpcServiceCallableFactoryClassHeaderComments(
+                    service.name()))
             .setAnnotations(createClassAnnotations(types))
             .setImplementsTypes(createClassImplements(types))
             .setName(className)

src/main/java/com/google/api/generator/gapic/composer/GrpcServiceStubClassComposer.java

@@ -140,6 +140,8 @@ public GapicClass generate(Service service, Map<String, Message> ignore) {
     ClassDefinition classDef =
         ClassDefinition.builder()
             .setPackageString(pakkage)
+            .setHeaderCommentStatements(
+                StubCommentComposer.createGrpcServiceStubClassHeaderComments(service.name()))
             .setAnnotations(createClassAnnotations())
             .setScope(ScopeNode.PUBLIC)
             .setName(className)

src/main/java/com/google/api/generator/gapic/composer/ServiceStubClassComposer.java

@@ -65,6 +65,8 @@ public GapicClass generate(Service service, Map<String, Message> messageTypes) {
     ClassDefinition classDef =
         ClassDefinition.builder()
             .setPackageString(pakkage)
+            .setHeaderCommentStatements(
+                StubCommentComposer.createServiceStubClassHeaderComments(service.name()))
             .setAnnotations(createClassAnnotations(types))
             .setIsAbstract(true)
             .setImplementsTypes(createClassImplements(types))

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<CommentStatement> 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<CommentStatement> 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<CommentStatement> 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()));
+  }
+}

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"
+          + " * <p>This class is for advanced usage.\n"
+          + " */\n"
           + "@Generated(\"by gapic-generator\")\n"
           + "public class GrpcEchoCallableFactory implements GrpcStubCallableFactory {\n"
           + "\n"

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"
+          + " * <p>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<EchoRequest, EchoResponse>"

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"
+          + " * <p>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"