[ggj][codegen] feat: add service.yaml and proto comments to package-i…

…nfo.java (#416)

* fix: refactor requestBuilder into separate method in ServiceClientClassComposer

* feat: add varargs to AnonClass and ref setter methods

* feat: add HTTP annotation parsing/validation

* feat: Generate RequestParamsExtractor in GrpcServiceStub

* feat: add GrpcPublisherStub test to exercise HTTP subfields

* fix: add ByteString to DefaultValueComposer

* fix: Use repeated field name for paged RPC unit tests

* fix: refactor exception field, use paged repeated field name, add pubsub client test

* fix: ensure all testgen methods throw Exceptions

* fix: Fix resname helper method names for of* and format*

* fix: use only generated resnames in codegen

* fix: propagate of*Name changes to resname codegen

* fix: fix method arg resname mappings, add logging test

* fix: ensure paged tests use the right repeated resp. type

* feat: add PackageInfoDefinition AST node

* feat: add package-info.java codegen

* feat: add Service.yaml parsing

* feat: add service.yaml and proto comments to package-info.java

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

@@ -15,15 +15,29 @@
 package com.google.api.generator.gapic.composer;
 
 import com.google.api.generator.engine.ast.AnnotationNode;
+import com.google.api.generator.engine.ast.CommentStatement;
 import com.google.api.generator.engine.ast.ConcreteReference;
+import com.google.api.generator.engine.ast.JavaDocComment;
 import com.google.api.generator.engine.ast.PackageInfoDefinition;
 import com.google.api.generator.engine.ast.TypeNode;
 import com.google.api.generator.gapic.model.GapicContext;
 import com.google.api.generator.gapic.model.GapicPackageInfo;
+import com.google.api.generator.gapic.model.Service;
 import com.google.common.base.Preconditions;
+import com.google.common.base.Strings;
 import javax.annotation.Generated;
 
 public class ClientLibraryPackageInfoComposer {
+  private static final String DIVIDER = "=======================";
+
+  private static final String PACKAGE_INFO_DESCRIPTION =
+      "The interfaces provided are listed below, along with usage samples.";
+
+  private static final String CLIENT_PATTERN = "%sClient";
+  private static final String PACKAGE_INFO_TITLE_PATTERN = "A client to %s";
+  private static final String SAMPLE_CODE_HEADER_PATTERN = "Sample for %s:";
+  private static final String SERVICE_DESCRIPTION_HEADER_PATTERN = "Service Description: %s";
+
   public static GapicPackageInfo generatePackageInfo(GapicContext context) {
     Preconditions.checkState(!context.services().isEmpty(), "No services found to generate");
     // Pick some service's package, as we assume they are all the same.
@@ -32,6 +46,7 @@ public static GapicPackageInfo generatePackageInfo(GapicContext context) {
     PackageInfoDefinition packageInfo =
         PackageInfoDefinition.builder()
             .setPakkage(libraryPakkage)
+            .setHeaderCommentStatements(createPackageInfoJavadoc(context))
             .setAnnotations(
                 AnnotationNode.builder()
                     .setType(TypeNode.withReference(ConcreteReference.withClazz(Generated.class)))
@@ -40,4 +55,45 @@ public static GapicPackageInfo generatePackageInfo(GapicContext context) {
             .build();
     return GapicPackageInfo.with(packageInfo);
   }
+
+  private static CommentStatement createPackageInfoJavadoc(GapicContext context) {
+    JavaDocComment.Builder javaDocCommentBuilder = JavaDocComment.builder();
+    if (context.hasServiceYamlProto()
+        && !Strings.isNullOrEmpty(context.serviceYamlProto().getTitle())) {
+      javaDocCommentBuilder =
+          javaDocCommentBuilder.addComment(
+              String.format(PACKAGE_INFO_TITLE_PATTERN, context.serviceYamlProto().getTitle()));
+    }
+
+    javaDocCommentBuilder = javaDocCommentBuilder.addParagraph(PACKAGE_INFO_DESCRIPTION);
+
+    for (Service service : context.services()) {
+      String javaClientName = String.format(CLIENT_PATTERN, service.name());
+      javaDocCommentBuilder =
+          javaDocCommentBuilder.addParagraph(
+              String.format("%s %s %s", DIVIDER, javaClientName, DIVIDER));
+
+      // TODO(miraleung): Paragraphs
+      if (service.hasDescription()) {
+        String[] descriptionParagraphs = service.description().split("\\r?\\n");
+        for (int i = 0; i < descriptionParagraphs.length; i++) {
+          if (i == 0) {
+            javaDocCommentBuilder =
+                javaDocCommentBuilder.addParagraph(
+                    String.format(SERVICE_DESCRIPTION_HEADER_PATTERN, descriptionParagraphs[i]));
+          } else {
+            javaDocCommentBuilder = javaDocCommentBuilder.addParagraph(descriptionParagraphs[i]);
+          }
+        }
+      }
+
+      javaDocCommentBuilder =
+          javaDocCommentBuilder.addParagraph(
+              String.format(SAMPLE_CODE_HEADER_PATTERN, javaClientName));
+
+      // TODO(summerji): Add package-info.java sample code here.
+    }
+
+    return CommentStatement.withComment(javaDocCommentBuilder.build());
+  }
 }