feat: inline disclaimer comment, use Sample/RegionTag, collect GapicClass samples (pt 2) (#970)

* chore: rename files

* feat: prepare for writing samples, include comment in inline samples

* chore: update test naming

* test: refactor grpc golden unit tests include samples

* test: integration goldens

* test: unit goldens

* nit refactor

* formatting

* refactor: move isProtoEmptyType, move handleDuplicateSamples, update sample name/file name

* fix - update unit goldens dir with lowercase dir

* test: SampleComposerUtilTest included

* fix: include header

Author: eaball35

src/main/java/com/google/api/generator/engine/ast/TypeNode.java

@@ -203,6 +203,11 @@ public boolean isProtoPrimitiveType() {
     return isPrimitiveType() || equals(TypeNode.STRING) || equals(TypeNode.BYTESTRING);
   }
 
+  public boolean isProtoEmptyType() {
+    return reference().pakkage().equals("com.google.protobuf")
+        && reference().name().equals("Empty");
+  }
+
   public boolean isSupertypeOrEquals(TypeNode other) {
     boolean oneTypeIsNull = equals(TypeNode.NULL) ^ other.equals(TypeNode.NULL);
     return !isPrimitiveType()

src/main/java/com/google/api/generator/engine/writer/JavaWriterVisitor.java

@@ -998,7 +998,7 @@ public void visit(ClassDefinition classDefinition) {
 
       // fixing region tag after formatting
       // formatter splits long region tags on multiple lines and moves the end tag up - doesn't meet
-      // tag requirements
+      // tag requirements. See https://github.com/google/google-java-format/issues/137
       if (classDefinition.regionTag() != null) {
         formattedClazz =
             formattedClazz.replaceAll(regionTagReplace, classDefinition.regionTag().generate());

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

@@ -21,10 +21,12 @@
 import com.google.api.generator.engine.ast.PackageInfoDefinition;
 import com.google.api.generator.engine.ast.TypeNode;
 import com.google.api.generator.engine.ast.VaporReference;
+import com.google.api.generator.gapic.composer.samplecode.SampleCodeWriter;
 import com.google.api.generator.gapic.composer.samplecode.ServiceClientHeaderSampleComposer;
 import com.google.api.generator.gapic.composer.utils.ClassNames;
 import com.google.api.generator.gapic.model.GapicContext;
 import com.google.api.generator.gapic.model.GapicPackageInfo;
+import com.google.api.generator.gapic.model.Sample;
 import com.google.api.generator.gapic.model.Service;
 import com.google.common.base.Preconditions;
 import com.google.common.base.Strings;
@@ -119,10 +121,11 @@ private static CommentStatement createPackageInfoJavadoc(GapicContext context) {
                   .setPakkage(service.pakkage())
                   .setName(ClassNames.getServiceClientClassName(service))
                   .build());
-      String packageInfoSampleCode =
-          ServiceClientHeaderSampleComposer.composeClassHeaderMethodSampleCode(
+      Sample packageInfoSampleCode =
+          ServiceClientHeaderSampleComposer.composeClassHeaderSample(
               service, clientType, context.resourceNames(), context.messages());
-      javaDocCommentBuilder.addSampleCode(packageInfoSampleCode);
+      javaDocCommentBuilder.addSampleCode(
+          SampleCodeWriter.writeInlineSample(packageInfoSampleCode.body()));
     }
 
     return CommentStatement.withComment(javaDocCommentBuilder.build());

src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceClientClassComposer.java

@@ -50,7 +50,9 @@
 import com.google.api.generator.engine.ast.Variable;
 import com.google.api.generator.engine.ast.VariableExpr;
 import com.google.api.generator.gapic.composer.comment.SettingsCommentComposer;
-import com.google.api.generator.gapic.composer.samplecode.SettingsSampleCodeComposer;
+import com.google.api.generator.gapic.composer.samplecode.SampleCodeWriter;
+import com.google.api.generator.gapic.composer.samplecode.SampleComposerUtil;
+import com.google.api.generator.gapic.composer.samplecode.SettingsSampleComposer;
 import com.google.api.generator.gapic.composer.store.TypeStore;
 import com.google.api.generator.gapic.composer.utils.ClassNames;
 import com.google.api.generator.gapic.composer.utils.PackageChecker;
@@ -59,6 +61,7 @@
 import com.google.api.generator.gapic.model.GapicContext;
 import com.google.api.generator.gapic.model.Method;
 import com.google.api.generator.gapic.model.Method.Stream;
+import com.google.api.generator.gapic.model.Sample;
 import com.google.api.generator.gapic.model.Service;
 import com.google.api.generator.gapic.utils.JavaStyle;
 import com.google.common.base.Preconditions;
@@ -100,12 +103,13 @@ public GapicClass generate(GapicContext context, Service service) {
     TypeStore typeStore = createDynamicTypes(service);
     String className = ClassNames.getServiceSettingsClassName(service);
     GapicClass.Kind kind = Kind.MAIN;
-
+    List<Sample> samples = new ArrayList<>();
+    List<CommentStatement> classHeaderComments =
+        createClassHeaderComments(service, typeStore.get(className), samples);
     ClassDefinition classDef =
         ClassDefinition.builder()
             .setPackageString(pakkage)
-            .setHeaderCommentStatements(
-                createClassHeaderComments(service, typeStore.get(className)))
+            .setHeaderCommentStatements(classHeaderComments)
             .setAnnotations(createClassAnnotations(service))
             .setScope(ScopeNode.PUBLIC)
             .setName(className)
@@ -122,11 +126,11 @@ public GapicClass generate(GapicContext context, Service service) {
             .setMethods(createClassMethods(service, typeStore))
             .setNestedClasses(Arrays.asList(createNestedBuilderClass(service, typeStore)))
             .build();
-    return GapicClass.create(kind, classDef);
+    return GapicClass.create(kind, classDef, SampleComposerUtil.handleDuplicateSamples(samples));
   }
 
   private static List<CommentStatement> createClassHeaderComments(
-      Service service, TypeNode classType) {
+      Service service, TypeNode classType, List<Sample> samples) {
     // Pick the first pure unary rpc method, if no such method exists, then pick the first in the
     // list.
     Optional<Method> methodOpt =
@@ -139,15 +143,22 @@ private static List<CommentStatement> createClassHeaderComments(
                     .orElse(service.methods().get(0)));
     Optional<String> methodNameOpt =
         methodOpt.isPresent() ? Optional.of(methodOpt.get().name()) : Optional.empty();
-    Optional<String> sampleCodeOpt =
-        SettingsSampleCodeComposer.composeSampleCode(
+    Optional<Sample> sampleCode =
+        SettingsSampleComposer.composeSettingsSample(
             methodNameOpt, ClassNames.getServiceSettingsClassName(service), classType);
+
+    Optional<String> docSampleCode = Optional.empty();
+    if (sampleCode.isPresent()) {
+      samples.add(sampleCode.get());
+      docSampleCode = Optional.of(SampleCodeWriter.writeInlineSample(sampleCode.get().body()));
+    }
+
     return SettingsCommentComposer.createClassHeaderComments(
         ClassNames.getServiceClientClassName(service),
         service.defaultHost(),
         service.isDeprecated(),
         methodNameOpt,
-        sampleCodeOpt,
+        docSampleCode,
         classType);
   }
 

src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceSettingsClassComposer.java

@@ -79,7 +79,9 @@
 import com.google.api.generator.engine.ast.Variable;
 import com.google.api.generator.engine.ast.VariableExpr;
 import com.google.api.generator.gapic.composer.comment.SettingsCommentComposer;
-import com.google.api.generator.gapic.composer.samplecode.SettingsSampleCodeComposer;
+import com.google.api.generator.gapic.composer.samplecode.SampleCodeWriter;
+import com.google.api.generator.gapic.composer.samplecode.SampleComposerUtil;
+import com.google.api.generator.gapic.composer.samplecode.SettingsSampleComposer;
 import com.google.api.generator.gapic.composer.store.TypeStore;
 import com.google.api.generator.gapic.composer.utils.ClassNames;
 import com.google.api.generator.gapic.composer.utils.PackageChecker;
@@ -91,6 +93,7 @@
 import com.google.api.generator.gapic.model.Message;
 import com.google.api.generator.gapic.model.Method;
 import com.google.api.generator.gapic.model.Method.Stream;
+import com.google.api.generator.gapic.model.Sample;
 import com.google.api.generator.gapic.model.Service;
 import com.google.api.generator.gapic.utils.JavaStyle;
 import com.google.common.base.Preconditions;
@@ -168,6 +171,7 @@ public GapicClass generate(GapicContext context, Service service) {
     String pakkage = String.format("%s.stub", service.pakkage());
     TypeStore typeStore = createDynamicTypes(service, pakkage);
 
+    List<Sample> samples = new ArrayList<>();
     Set<String> deprecatedSettingVarNames = new HashSet<>();
     Map<String, VariableExpr> methodSettingsMemberVarExprs =
         createMethodSettingsClassMemberVarExprs(
@@ -177,12 +181,12 @@ public GapicClass generate(GapicContext context, Service service) {
             /* isNestedClass= */ false,
             deprecatedSettingVarNames);
     String className = ClassNames.getServiceStubSettingsClassName(service);
-
+    List<CommentStatement> classHeaderComments =
+        createClassHeaderComments(service, typeStore.get(className), samples);
     ClassDefinition classDef =
         ClassDefinition.builder()
             .setPackageString(pakkage)
-            .setHeaderCommentStatements(
-                createClassHeaderComments(service, typeStore.get(className)))
+            .setHeaderCommentStatements(classHeaderComments)
             .setAnnotations(createClassAnnotations(service))
             .setScope(ScopeNode.PUBLIC)
             .setName(className)
@@ -196,7 +200,8 @@ public GapicClass generate(GapicContext context, Service service) {
             .setNestedClasses(
                 Arrays.asList(createNestedBuilderClass(service, serviceConfig, typeStore)))
             .build();
-    return GapicClass.create(GapicClass.Kind.STUB, classDef);
+    return GapicClass.create(
+        GapicClass.Kind.STUB, classDef, SampleComposerUtil.handleDuplicateSamples(samples));
   }
 
   protected MethodDefinition createDefaultCredentialsProviderBuilderMethod() {
@@ -376,7 +381,7 @@ private List<AnnotationNode> createClassAnnotations(Service service) {
   }
 
   private static List<CommentStatement> createClassHeaderComments(
-      Service service, TypeNode classType) {
+      Service service, TypeNode classType, List<Sample> samples) {
     // Pick the first pure unary rpc method, if no such method exists, then pick the first in the
     // list.
     Optional<Method> methodOpt =
@@ -389,16 +394,22 @@ private static List<CommentStatement> createClassHeaderComments(
                     .orElse(service.methods().get(0)));
     Optional<String> methodNameOpt =
         methodOpt.isPresent() ? Optional.of(methodOpt.get().name()) : Optional.empty();
-    Optional<String> sampleCodeOpt =
-        SettingsSampleCodeComposer.composeSampleCode(
+    Optional<Sample> sampleCode =
+        SettingsSampleComposer.composeSettingsSample(
             methodNameOpt, ClassNames.getServiceSettingsClassName(service), classType);
 
+    Optional<String> docSampleCode = Optional.empty();
+    if (sampleCode.isPresent()) {
+      samples.add(sampleCode.get());
+      docSampleCode = Optional.of(SampleCodeWriter.writeInlineSample(sampleCode.get().body()));
+    }
+
     return SettingsCommentComposer.createClassHeaderComments(
         ClassNames.getServiceStubClassName(service),
         service.defaultHost(),
         service.isDeprecated(),
         methodNameOpt,
-        sampleCodeOpt,
+        docSampleCode,
         classType);
   }
 

src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceStubSettingsClassComposer.java

@@ -21,11 +21,9 @@
 import java.util.regex.Pattern;
 
 public final class SampleBodyJavaFormatter {
-
   private SampleBodyJavaFormatter() {}
 
   private static final Formatter FORMATTER = new Formatter();
-
   private static final String FAKE_CLASS_TITLE = "public class FakeClass { void fakeMethod() {\n";
   private static final String FAKE_CLASS_CLOSE = "}}";
 

src/main/java/com/google/api/generator/gapic/composer/samplecode/SampleBodyJavaFormatter.java

@@ -15,6 +15,8 @@
 package com.google.api.generator.gapic.composer.samplecode;
 
 import com.google.api.generator.engine.ast.ClassDefinition;
+import com.google.api.generator.engine.ast.Expr;
+import com.google.api.generator.engine.ast.ExprStatement;
 import com.google.api.generator.engine.ast.Statement;
 import com.google.api.generator.engine.writer.JavaWriterVisitor;
 import com.google.api.generator.gapic.model.Sample;
@@ -32,6 +34,11 @@ public static String writeExecutableSample(Sample sample, String packkage) {
     return write(SampleComposer.composeExecutableSample(sample, packkage));
   }
 
+  @VisibleForTesting
+  public static String write(Statement... statement) {
+    return write(Arrays.asList(statement));
+  }
+
   @VisibleForTesting
   public static String write(List<Statement> statements) {
     JavaWriterVisitor visitor = new JavaWriterVisitor();
@@ -50,7 +57,8 @@ public static String write(ClassDefinition classDefinition) {
     return visitor.write();
   }
 
-  public static String write(Statement... statement) {
-    return write(Arrays.asList(statement));
+  @VisibleForTesting
+  public static String write(Expr expr) {
+    return write(ExprStatement.withExpr(expr));
   }
 }

src/main/java/com/google/api/generator/gapic/composer/samplecode/SampleCodeWriter.java

@@ -0,0 +1,113 @@
+// Copyright 2022 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.samplecode;
+
+import com.google.api.generator.engine.ast.AssignmentExpr;
+import com.google.api.generator.engine.ast.MethodInvocationExpr;
+import com.google.api.generator.engine.ast.TypeNode;
+import com.google.api.generator.engine.ast.VariableExpr;
+import com.google.api.generator.gapic.model.MethodArgument;
+import com.google.api.generator.gapic.model.ResourceName;
+import com.google.api.generator.gapic.model.Sample;
+import com.google.api.generator.gapic.utils.JavaStyle;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+public class SampleComposerUtil {
+  // Assign client variable expr with create client.
+  // e.g EchoClient echoClient = EchoClient.create()
+  static AssignmentExpr assignClientVariableWithCreateMethodExpr(VariableExpr clientVarExpr) {
+    return AssignmentExpr.builder()
+        .setVariableExpr(clientVarExpr.toBuilder().setIsDecl(true).build())
+        .setValueExpr(
+            MethodInvocationExpr.builder()
+                .setStaticReferenceType(clientVarExpr.variable().type())
+                .setReturnType(clientVarExpr.variable().type())
+                .setMethodName("create")
+                .build())
+        .build();
+  }
+
+  static boolean isStringTypedResourceName(
+      MethodArgument arg, Map<String, ResourceName> resourceNames) {
+    return arg.type().equals(TypeNode.STRING)
+        && arg.field().hasResourceReference()
+        && resourceNames.containsKey(arg.field().resourceReference().resourceTypeString());
+  }
+
+  static String createOverloadDisambiguation(List<VariableExpr> methodArgVarExprs) {
+    if (methodArgVarExprs.isEmpty()) {
+      return "Noargs";
+    }
+    return methodArgVarExprs.stream()
+        .map(
+            arg ->
+                JavaStyle.toUpperCamelCase(
+                    arg.variable().type().reference() == null
+                        ? arg.variable().type().typeKind().name().toLowerCase()
+                        : arg.variable().type().reference().name().toLowerCase()))
+        .collect(Collectors.joining());
+  }
+
+  public static List<Sample> handleDuplicateSamples(List<Sample> samples) {
+    //  grab all distinct samples and group by sample name
+    //  ie: { "echo", ["echo(request"],
+    //        "echoString", ["echo(parent)", "echo(child)", "echo(context)"],
+    //        "echoDelete", ["echo.delete(request)"] }
+    Map<String, List<Sample>> distinctSamplesGroupedByName =
+        samples.stream().distinct().collect(Collectors.groupingBy(s -> s.name()));
+
+    // collect samples that don't have duplicates
+    // ie: ["echo", "echoDelete"]
+    List<Sample> uniqueSamples =
+        distinctSamplesGroupedByName.entrySet().stream()
+            .filter(entry -> entry.getValue().size() < 2)
+            .map(entry -> entry.getValue().get(0))
+            .collect(Collectors.toList());
+
+    if (uniqueSamples.size() == distinctSamplesGroupedByName.size()) {
+      return uniqueSamples;
+    }
+
+    // collect samples that do have duplicates
+    // ie: ["echoString"]
+    List<Map.Entry<String, List<Sample>>> duplicateDistinctSamples =
+        distinctSamplesGroupedByName.entrySet().stream()
+            .filter(entry -> entry.getValue().size() > 1)
+            .collect(Collectors.toList());
+
+    // update similar samples regionTag/name so filesname/regiontag are unique
+    // ie: ["echo", "echoDelete", "echoString", "echoString1"]
+    for (Map.Entry<String, List<Sample>> entry : duplicateDistinctSamples) {
+      int sampleNum = 0;
+      for (Sample sample : entry.getValue()) {
+        Sample uniqueSample = sample;
+        //  first sample will be "canonical", not updating name
+        if (sampleNum != 0) {
+          uniqueSample =
+              sample.withRegionTag(
+                  sample
+                      .regionTag()
+                      .withOverloadDisambiguation(
+                          sample.regionTag().overloadDisambiguation() + sampleNum));
+        }
+        uniqueSamples.add(uniqueSample);
+        sampleNum++;
+      }
+    }
+    return uniqueSamples;
+  }
+}