refactor(gapic): use overloads in SampleComposer instead of Sample property for custom comments

Author: lqiu96

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

@@ -30,6 +30,7 @@
 import com.google.api.gax.rpc.StubSettings;
 import com.google.api.gax.rpc.TransportChannelProvider;
 import com.google.api.gax.rpc.UnaryCallSettings;
+import com.google.api.generator.gapic.composer.comment.CommentComposer;
 import com.google.api.generator.engine.ast.AnnotationNode;
 import com.google.api.generator.engine.ast.CastExpr;
 import com.google.api.generator.engine.ast.ClassDefinition;
@@ -169,7 +170,7 @@ private static List<CommentStatement> createClassHeaderComments(
     Optional<String> docSampleCode = Optional.empty();
     if (sampleCode.isPresent()) {
       samples.add(sampleCode.get());
-      docSampleCode = Optional.of(SampleCodeWriter.writeInlineSample(sampleCode.get()));
+      docSampleCode = Optional.of(SampleCodeWriter.writeInlineSample(sampleCode.get(), CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT_BASE));
     }
     // Create a sample for a LRO method using LRO-specific RetrySettings, if one exists in the
     // service.
@@ -188,7 +189,7 @@ private static List<CommentStatement> createClassHeaderComments(
     if (lroSampleCode.isPresent()) {
       samples.add(lroSampleCode.get());
       lroDocSampleCode =
-          Optional.of(SampleCodeWriter.writeInlineSample(lroSampleCode.get()));
+          Optional.of(SampleCodeWriter.writeInlineSample(lroSampleCode.get(), CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT_BASE));
     }
 
     return SettingsCommentComposer.createClassHeaderComments(

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

@@ -14,6 +14,7 @@
 
 package com.google.api.generator.gapic.composer.common;
 
+import com.google.api.generator.gapic.composer.comment.CommentComposer;
 import com.google.api.MonitoredResourceDescriptor;
 import com.google.api.core.ApiFunction;
 import com.google.api.core.ApiFuture;
@@ -459,7 +460,7 @@ private static List<CommentStatement> createClassHeaderComments(
     Optional<String> docSampleCode = Optional.empty();
     if (sampleCode.isPresent()) {
       samples.add(sampleCode.get());
-      docSampleCode = Optional.of(SampleCodeWriter.writeInlineSample(sampleCode.get()));
+      docSampleCode = Optional.of(SampleCodeWriter.writeInlineSample(sampleCode.get(), CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT_BASE));
     }
     // Create a sample for a LRO method using LRO-specific RetrySettings, if one exists in the
     // service.
@@ -478,7 +479,7 @@ private static List<CommentStatement> createClassHeaderComments(
     if (lroSampleCode.isPresent()) {
       samples.add(lroSampleCode.get());
       lroDocSampleCode =
-          Optional.of(SampleCodeWriter.writeInlineSample(lroSampleCode.get()));
+          Optional.of(SampleCodeWriter.writeInlineSample(lroSampleCode.get(), CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT_BASE));
     }
 
     return SettingsCommentComposer.createClassHeaderComments(

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

@@ -34,10 +34,18 @@ public static String writeInlineSample(Sample sample) {
     return write(SampleComposer.composeInlineSample(sample));
   }
 
+  public static String writeInlineSample(Sample sample, List<Statement> sampleComment) {
+    return write(SampleComposer.composeInlineSample(sample, sampleComment));
+  }
+
   public static String writeExecutableSample(Sample sample, String packkage) {
     return write(SampleComposer.composeExecutableSample(sample, packkage));
   }
 
+  public static String writeExecutableSample(Sample sample, String packkage, List<Statement> sampleComment) {
+    return write(SampleComposer.composeExecutableSample(sample, packkage, sampleComment));
+  }
+
   @VisibleForTesting
   public static String write(Statement... statement) {
     return write(Arrays.asList(statement));

sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/samplecode/SampleComposer.java

@@ -42,26 +42,26 @@ static List<Statement> composeInlineSample(List<Statement> sampleBody) {
   }
 
   static List<Statement> composeInlineSample(Sample sample) {
-    return bodyWithComment(
-        sample.sampleComment() != null
-            ? sample.sampleComment()
-            : CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT,
-        sample.body());
+    return composeInlineSample(sample, CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT);
+  }
+
+  static List<Statement> composeInlineSample(Sample sample, List<Statement> sampleComment) {
+    return bodyWithComment(sampleComment, sample.body());
   }
 
   //  "Executable" meaning it includes the necessary code to execute java code,
   //  still may require additional configuration to actually execute generated sample code
   static ClassDefinition composeExecutableSample(Sample sample, String pakkage) {
+    return composeExecutableSample(sample, pakkage, CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT);
+  }
+
+  static ClassDefinition composeExecutableSample(Sample sample, String pakkage, List<Statement> sampleComment) {
     return createExecutableSample(
         sample.fileHeader(),
         pakkage,
         sample.name(),
         sample.variableAssignments(),
-        bodyWithComment(
-            sample.sampleComment() != null
-                ? sample.sampleComment()
-                : CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT,
-            sample.body()),
+        bodyWithComment(sampleComment, sample.body()),
         sample.regionTag());
   }
 

sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/samplecode/SettingsSampleComposer.java

@@ -26,7 +26,6 @@
 import com.google.api.generator.engine.ast.Variable;
 import com.google.api.generator.engine.ast.VariableExpr;
 import com.google.api.generator.gapic.model.RegionTag;
-import com.google.api.generator.gapic.composer.comment.CommentComposer;
 import com.google.api.generator.gapic.model.Sample;
 import com.google.api.generator.gapic.utils.JavaStyle;
 import java.time.Duration;
@@ -248,7 +247,7 @@ public static Optional<Sample> composeSettingsSample(
         Sample.builder()
             .setBody(statements)
             .setRegionTag(regionTag)
-            .setSampleComment(CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT_BASE)
+
             .build());
   }
 
@@ -444,7 +443,7 @@ public static Optional<Sample> composeLroSettingsSample(
         Sample.builder()
             .setBody(statements)
             .setRegionTag(regionTag)
-            .setSampleComment(CommentComposer.AUTO_GENERATED_SAMPLE_COMMENT_BASE)
+
             .build());
   }
 }

sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/model/Sample.java

@@ -20,7 +20,6 @@
 import com.google.auto.value.AutoValue;
 import com.google.common.collect.ImmutableList;
 import java.util.List;
-import javax.annotation.Nullable;
 
 /**
  * This model represents a generated code sample. It contains the information needed to generate a
@@ -40,8 +39,7 @@ public abstract class Sample {
 
   public abstract boolean isCanonical();
 
-  @Nullable
-  public abstract List<Statement> sampleComment();
+
 
   public static Builder builder() {
     return new AutoValue_Sample.Builder()
@@ -92,7 +90,7 @@ public abstract static class Builder {
 
     public abstract Builder setIsCanonical(boolean isCanonical);
 
-    public abstract Builder setSampleComment(List<Statement> sampleComment);
+
 
     abstract Builder setName(String name);
 

sdk-platform-java/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/samples/servicesettings/SyncEcho.golden

@@ -32,6 +32,11 @@ public class SyncEcho {
     // - It may require correct/in-range values for request initialization.
     // - It may require specifying regional endpoints when creating the service client as shown in
     // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
+    // - The samples create a client that can be re-used for multiple requests
+    // and are expected to be long-lived.
+    // The clients should be resource managed properly and eventually closed.
+    // For more information on client lifecycle, see
+    // https://docs.cloud.google.com/java/docs/client-lifecycle
     EchoSettings.Builder echoSettingsBuilder = EchoSettings.newBuilder();
     echoSettingsBuilder
         .echoSettings()

sdk-platform-java/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/samples/servicesettings/SyncEchoShouldGenerateAsUsual.golden

@@ -32,6 +32,11 @@ public class SyncEchoShouldGenerateAsUsual {
     // - It may require correct/in-range values for request initialization.
     // - It may require specifying regional endpoints when creating the service client as shown in
     // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
+    // - The samples create a client that can be re-used for multiple requests
+    // and are expected to be long-lived.
+    // The clients should be resource managed properly and eventually closed.
+    // For more information on client lifecycle, see
+    // https://docs.cloud.google.com/java/docs/client-lifecycle
     EchoServiceShouldGeneratePartialUsualSettings.Builder
         echoServiceShouldGeneratePartialUsualSettingsBuilder =
             EchoServiceShouldGeneratePartialUsualSettings.newBuilder();

sdk-platform-java/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/samples/servicesettings/SyncFastFibonacci.golden

@@ -32,6 +32,11 @@ public class SyncFastFibonacci {
     // - It may require correct/in-range values for request initialization.
     // - It may require specifying regional endpoints when creating the service client as shown in
     // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
+    // - The samples create a client that can be re-used for multiple requests
+    // and are expected to be long-lived.
+    // The clients should be resource managed properly and eventually closed.
+    // For more information on client lifecycle, see
+    // https://docs.cloud.google.com/java/docs/client-lifecycle
     DeprecatedServiceSettings.Builder deprecatedServiceSettingsBuilder =
         DeprecatedServiceSettings.newBuilder();
     deprecatedServiceSettingsBuilder

sdk-platform-java/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/samples/servicesettings/SyncWait.golden

@@ -35,6 +35,11 @@ public class SyncWait {
     // - It may require correct/in-range values for request initialization.
     // - It may require specifying regional endpoints when creating the service client as shown in
     // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
+    // - The samples create a client that can be re-used for multiple requests
+    // and are expected to be long-lived.
+    // The clients should be resource managed properly and eventually closed.
+    // For more information on client lifecycle, see
+    // https://docs.cloud.google.com/java/docs/client-lifecycle
     EchoSettings.Builder echoSettingsBuilder = EchoSettings.newBuilder();
     TimedRetryAlgorithm timedRetryAlgorithm =
         OperationalTimedPollAlgorithm.create(