feat: add full RetrySettings sample code to Settings classes (#3056)

Fixes #2596 ☕️

Author: alicejli

gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/SettingsCommentComposer.java

@@ -39,7 +39,13 @@ public class SettingsCommentComposer {
   private static final String CLASS_HEADER_DEFAULT_ADDRESS_PORT_PATTERN =
       "The default service address (%s) and default port (%d) are used.";
   private static final String CLASS_HEADER_SAMPLE_CODE_PATTERN =
-      "For example, to set the total timeout of %s to 30 seconds:";
+      "For example, to set the [RetrySettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.retrying.RetrySettings) of %s:";
+
+  private static final String CLASS_HEADER_LRO_SAMPLE_CODE_PATTERN =
+      "To configure the RetrySettings of a Long Running Operation method, create an OperationTimedPollAlgorithm object and update the RPC's polling algorithm. For example, to configure the RetrySettings for %s:";
+
+  private static final String CLASS_HEADER_SAMPLE_CODE_SUFFIX =
+      "Please refer to the [Client Side Retry Guide](https://github.com/googleapis/google-cloud-java/blob/main/docs/client_retries.md) for additional support in setting retries.";
 
   private static final String CLASS_HEADER_BUILDER_DESCRIPTION =
       "The builder of this class is recursive, so contained classes are themselves builders. When"
@@ -139,6 +145,8 @@ public static List<CommentStatement> createClassHeaderComments(
       boolean isDeprecated,
       Optional<String> methodNameOpt,
       Optional<String> sampleCodeOpt,
+      Optional<String> lroMethodNameOpt,
+      Optional<String> lroSampleCodeOpt,
       TypeNode classType) {
     // Split default address and port.
     int colonIndex = defaultHost.indexOf(COLON);
@@ -170,7 +178,18 @@ public static List<CommentStatement> createClassHeaderComments(
                   String.format(
                       CLASS_HEADER_SAMPLE_CODE_PATTERN,
                       JavaStyle.toLowerCamelCase(methodNameOpt.get())))
-              .addSampleCode(sampleCodeOpt.get());
+              .addSampleCode(sampleCodeOpt.get())
+              .addComment(CLASS_HEADER_SAMPLE_CODE_SUFFIX);
+    }
+
+    if (lroMethodNameOpt.isPresent() && lroSampleCodeOpt.isPresent()) {
+      javaDocCommentBuilder =
+          javaDocCommentBuilder
+              .addParagraph(
+                  String.format(
+                      CLASS_HEADER_LRO_SAMPLE_CODE_PATTERN,
+                      JavaStyle.toLowerCamelCase(lroMethodNameOpt.get())))
+              .addSampleCode(lroSampleCodeOpt.get());
     }
 
     if (isDeprecated) {

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

@@ -148,19 +148,39 @@ private static List<CommentStatement> createClassHeaderComments(
     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()));
     }
+    // Create a sample for a LRO method using LRO-specific RetrySettings, if one exists in the
+    // service.
+    Optional<Method> lroMethodOpt =
+        service.methods().isEmpty()
+            ? Optional.empty()
+            : service.methods().stream()
+                .filter(m -> m.stream() == Stream.NONE && m.hasLro())
+                .findFirst();
+    Optional<String> lroMethodNameOpt =
+        lroMethodOpt.isPresent() ? Optional.of(lroMethodOpt.get().name()) : Optional.empty();
+    Optional<Sample> lroSampleCode =
+        SettingsSampleComposer.composeLroSettingsSample(
+            lroMethodNameOpt, ClassNames.getServiceSettingsClassName(service), classType);
+    Optional<String> lroDocSampleCode = Optional.empty();
+    if (lroSampleCode.isPresent()) {
+      samples.add(lroSampleCode.get());
+      lroDocSampleCode =
+          Optional.of(SampleCodeWriter.writeInlineSample(lroSampleCode.get().body()));
+    }
 
     return SettingsCommentComposer.createClassHeaderComments(
         ClassNames.getServiceClientClassName(service),
         service.defaultHost(),
         service.isDeprecated(),
         methodNameOpt,
         docSampleCode,
+        lroMethodNameOpt,
+        lroDocSampleCode,
         classType);
   }
 

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

@@ -423,22 +423,43 @@ private static List<CommentStatement> createClassHeaderComments(
                     .findFirst()
                     .orElse(service.methods().get(0)));
     Optional<String> methodNameOpt = methodOpt.map(Method::name);
+
     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()));
     }
+    // Create a sample for a LRO method using LRO-specific RetrySettings, if one exists in the
+    // service.
+    Optional<Method> lroMethodOpt =
+        service.methods().isEmpty()
+            ? Optional.empty()
+            : service.methods().stream()
+                .filter(m -> m.stream() == Stream.NONE && m.hasLro())
+                .findFirst();
+    Optional<String> lroMethodNameOpt =
+        lroMethodOpt.isPresent() ? Optional.of(lroMethodOpt.get().name()) : Optional.empty();
+    Optional<Sample> lroSampleCode =
+        SettingsSampleComposer.composeLroSettingsSample(
+            lroMethodNameOpt, ClassNames.getServiceSettingsClassName(service), classType);
+    Optional<String> lroDocSampleCode = Optional.empty();
+    if (lroSampleCode.isPresent()) {
+      samples.add(lroSampleCode.get());
+      lroDocSampleCode =
+          Optional.of(SampleCodeWriter.writeInlineSample(lroSampleCode.get().body()));
+    }
 
     return SettingsCommentComposer.createClassHeaderComments(
         ClassNames.getServiceStubClassName(service),
         service.defaultHost(),
         service.isDeprecated(),
         methodNameOpt,
         docSampleCode,
+        lroMethodNameOpt,
+        lroDocSampleCode,
         classType);
   }