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

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/AbstractServiceSettingsClassComposer.java

@@ -50,7 +50,8 @@
 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.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 +60,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 +102,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 +125,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, 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 +142,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/AbstractServiceStubSettingsClassComposer.java

@@ -79,7 +79,8 @@
 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.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 +92,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 +170,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 +180,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 +199,7 @@ 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, samples);
   }
 
   protected MethodDefinition createDefaultCredentialsProviderBuilderMethod() {
@@ -376,7 +379,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 +392,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/samplecode/SampleBodyJavaFormatter.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/SampleCodeWriter.java

@@ -32,6 +32,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();
@@ -49,8 +54,4 @@ public static String write(ClassDefinition classDefinition) {
     classDefinition.accept(visitor);
     return visitor.write();
   }
-
-  public static String write(Statement... statement) {
-    return write(Arrays.asList(statement));
-  }
 }

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

@@ -0,0 +1,65 @@
+// 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.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 boolean isProtoEmptyType(TypeNode type) {
+    return type.reference().pakkage().equals("com.google.protobuf")
+        && type.reference().name().equals("Empty");
+  }
+
+  static String createOverloadDisambiguation(List<VariableExpr> methodArgVarExprs) {
+    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());
+  }
+}