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

Fixes #2596 ☕️

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);
  }