feat(comment): autoconfig gen draft2 javadoc2

src/main/java/com/google/api/generator/spring/composer/SpringAutoConfigClassComposer.java

@@ -48,6 +48,7 @@
 import com.google.api.generator.gapic.model.GapicContext;
 import com.google.api.generator.gapic.model.GapicServiceConfig;
 import com.google.api.generator.gapic.model.Service;
+import com.google.api.generator.spring.composer.comment.SpringAutoconfigCommentComposer;
 import com.google.api.generator.spring.utils.LoggerUtils;
 import com.google.api.generator.spring.utils.Utils;
 import com.google.common.base.CaseFormat;
@@ -100,6 +101,8 @@ public GapicClass generate(GapicContext context, Service service) {
             .setPackageString(packageName)
             .setName(className)
             .setScope(ScopeNode.PUBLIC)
+            .setHeaderCommentStatements(
+                SpringAutoconfigCommentComposer.createClassHeaderComments(className, serviceName))
             .setStatements(createMemberVariables(service, packageName, types, gapicServiceConfig))
             .setMethods(
                 Arrays.asList(
@@ -331,6 +334,8 @@ private static MethodDefinition createCredentialsProviderBeanMethod(
 
     return MethodDefinition.builder()
         .setName(methodName)
+        .setHeaderCommentStatements(
+            SpringAutoconfigCommentComposer.createCredentialsProviderBeanComment())
         .setScope(ScopeNode.PUBLIC)
         .setReturnType(types.get("CredentialsProvider"))
         .setAnnotations(
@@ -359,6 +364,8 @@ private static MethodDefinition createTransportChannelProviderBeanMethod(
             .build();
 
     return MethodDefinition.builder()
+        .setHeaderCommentStatements(
+            SpringAutoconfigCommentComposer.createTransportChannelProviderComment())
         .setName(methodName)
         .setScope(ScopeNode.PUBLIC)
         .setReturnType(STATIC_TYPES.get("TransportChannelProvider"))
@@ -780,8 +787,15 @@ private static MethodDefinition createClientBeanMethod(
             .setArguments(serviceSettingsBuilt)
             .build();
 
+    String methodName =
+        CaseFormat.UPPER_CAMEL.to(CaseFormat.LOWER_CAMEL, service.name()) + "Client";
+    String propertiesClassName = service.name() + "Properties";
+
     return MethodDefinition.builder()
-        .setName(clientName)
+        .setHeaderCommentStatements(
+            SpringAutoconfigCommentComposer.createClientBeanComment(
+                service.name(), propertiesClassName, transportChannelProviderName))
+        .setName(methodName)
         .setScope(ScopeNode.PUBLIC)
         .setReturnType(types.get("ServiceClient"))
         .setArguments(

src/main/java/com/google/api/generator/spring/composer/SpringPropertiesClassComposer.java

@@ -41,6 +41,7 @@
 import com.google.api.generator.gapic.model.GapicContext;
 import com.google.api.generator.gapic.model.GapicServiceConfig;
 import com.google.api.generator.gapic.model.Service;
+import com.google.api.generator.spring.composer.comment.SpringPropertiesCommentComposer;
 import com.google.api.generator.spring.utils.Utils;
 import com.google.common.base.CaseFormat;
 import com.google.common.base.Joiner;
@@ -80,6 +81,9 @@ public GapicClass generate(GapicContext context, Service service) {
 
     ClassDefinition classDef =
         ClassDefinition.builder()
+            .setHeaderCommentStatements(
+                SpringPropertiesCommentComposer.createClassHeaderComments(
+                    className, service.name()))
             .setPackageString(packageName)
             .setName(className)
             .setScope(ScopeNode.PUBLIC)

src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java

@@ -0,0 +1,106 @@
+// 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.spring.composer.comment;
+
+import com.google.api.generator.engine.ast.CommentStatement;
+import com.google.api.generator.engine.ast.JavaDocComment;
+import com.google.api.generator.gapic.composer.comment.CommentComposer;
+import com.google.common.base.CaseFormat;
+import java.util.Arrays;
+import java.util.List;
+
+public class SpringAutoconfigCommentComposer {
+
+  private static final String CLASS_HEADER_SUMMARY_PATTERN =
+      "Auto-configuration for {@link %sClient}.";
+  private static final String CLASS_HEADER_GENERAL_DESCRIPTION =
+      "Provides auto-configuration for Spring Boot";
+  private static final String CLASS_HEADER_DEFAULTS_DESCRIPTION =
+      "The default instance has everything set to sensible defaults:";
+  private static final String CLASS_HEADER_DEFAULTS_CREDENTIALS_DESCRIPTION =
+      "Credentials are acquired automatically through Application Default Credentials.";
+  private static final String CLASS_HEADER_DEFAULTS_TRANSPORT_DESCRIPTION =
+      "The default transport provider is used.";
+  private static final String CLASS_HEADER_DEFAULTS_RETRIES_DESCRIPTION =
+      "Retries are configured for idempotent methods but not for non-idempotent methods.";
+
+  public static final String CREDENTIALS_PROVIDER_GENERAL_DESCRIPTION =
+      "Obtains the default credentials provider. The used key will be obtained from Spring Boot "
+          + "configuration data files.";
+
+  public static final String TRANSPORT_CHANNEL_PROVIDER_GENERAL_DESCRIPTION =
+      "Returns the default channel provider. The default is gRPC and will default to it unless the "
+          + "useRest option is provided to use HTTP transport instead";
+  public static final String CLIENT_BEAN_GENERAL_DESCRIPTION =
+      "Provides a %sClient bean configured to "
+          + "use the default credentials provider (obtained with %sCredentials()) and its default "
+          + "transport channel provider (%s()). It also configures the quota project ID if provided. It "
+          + "will configure an executor provider in case there is more than one thread configured "
+          + "in the client ";
+
+  public static final String CLIENT_BEAN_RETRY_SETTINGS_DESCRIPTION =
+      "Individual retry settings "
+          + "are configured as well. It will use the relevant client library's default retry "
+          + "settings when they are not specified in %s.";
+
+  public SpringAutoconfigCommentComposer() {}
+
+  public static List<CommentStatement> createClassHeaderComments(
+      String configuredClassName, String serviceName) {
+
+    JavaDocComment.Builder javaDocCommentBuilder =
+        JavaDocComment.builder()
+            .addUnescapedComment(String.format(CLASS_HEADER_SUMMARY_PATTERN, serviceName))
+            .addParagraph(CLASS_HEADER_GENERAL_DESCRIPTION)
+            .addParagraph(CLASS_HEADER_DEFAULTS_DESCRIPTION)
+            .addUnorderedList(
+                Arrays.asList(
+                    CLASS_HEADER_DEFAULTS_TRANSPORT_DESCRIPTION,
+                    CLASS_HEADER_DEFAULTS_CREDENTIALS_DESCRIPTION,
+                    CLASS_HEADER_DEFAULTS_RETRIES_DESCRIPTION));
+
+    return Arrays.asList(
+        CommentComposer.AUTO_GENERATED_CLASS_COMMENT,
+        CommentStatement.withComment(javaDocCommentBuilder.build()));
+  }
+
+  public static CommentStatement createCredentialsProviderBeanComment() {
+    return CommentStatement.withComment(
+        JavaDocComment.builder().addParagraph(CREDENTIALS_PROVIDER_GENERAL_DESCRIPTION).build());
+  }
+
+  public static CommentStatement createTransportChannelProviderComment() {
+    return CommentStatement.withComment(
+        JavaDocComment.builder()
+            .addParagraph(TRANSPORT_CHANNEL_PROVIDER_GENERAL_DESCRIPTION)
+            .build());
+  }
+
+  public static CommentStatement createClientBeanComment(
+      String serviceName, String propertiesClazzName, String channelProviderName) {
+    String credentialsBaseName = CaseFormat.UPPER_CAMEL.to(CaseFormat.LOWER_CAMEL, serviceName);
+    return CommentStatement.withComment(
+        JavaDocComment.builder()
+            .addParagraph(
+                String.format(
+                    CLIENT_BEAN_GENERAL_DESCRIPTION,
+                    serviceName,
+                    credentialsBaseName,
+                    channelProviderName))
+            .addParagraph(
+                String.format(CLIENT_BEAN_RETRY_SETTINGS_DESCRIPTION, propertiesClazzName))
+            .build());
+  }
+}

src/main/java/com/google/api/generator/spring/composer/comment/SpringPropertiesCommentComposer.java

@@ -0,0 +1,37 @@
+// 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.spring.composer.comment;
+
+import com.google.api.generator.engine.ast.CommentStatement;
+import com.google.api.generator.engine.ast.JavaDocComment;
+import com.google.api.generator.gapic.composer.comment.CommentComposer;
+import java.util.Arrays;
+import java.util.List;
+
+public class SpringPropertiesCommentComposer {
+  private static final String CLASS_HEADER_GENERAL_DESCRIPTION =
+      "Provides default property values for %s client bean";
+
+  public static List<CommentStatement> createClassHeaderComments(
+      String configuredClassName, String serviceName) {
+
+    JavaDocComment.Builder javaDocCommentBuilder =
+        JavaDocComment.builder()
+            .addParagraph(String.format(CLASS_HEADER_GENERAL_DESCRIPTION, serviceName));
+    return Arrays.asList(
+        CommentComposer.AUTO_GENERATED_CLASS_COMMENT,
+        CommentStatement.withComment(javaDocCommentBuilder.build()));
+  }
+}

src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfiguration.golden

@@ -19,6 +19,20 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties
 import org.springframework.context.annotation.Bean;
 import org.threeten.bp.Duration;
 
+// AUTO-GENERATED DOCUMENTATION AND CLASS.
+/**
+ * Auto-configuration for {@link EchoClient}.
+ *
+ * <p>Provides auto-configuration for Spring Boot
+ *
+ * <p>The default instance has everything set to sensible defaults:
+ *
+ * <ul>
+ *   <li>The default transport provider is used.
+ *   <li>Credentials are acquired automatically through Application Default Credentials.
+ *   <li>Retries are configured for idempotent methods but not for non-idempotent methods.
+ * </ul>
+ */
 @AutoConfiguration
 @ConditionalOnClass(EchoClient.class)
 @ConditionalOnProperty(
@@ -33,18 +47,36 @@ public class EchoSpringAutoConfiguration {
     this.clientProperties = clientProperties;
   }
 
+  /**
+   * Obtains the default credentials provider. The used key will be obtained from Spring Boot
+   * configuration data files.
+   */
   @Bean
   @ConditionalOnMissingBean
   public CredentialsProvider echoCredentials() throws IOException {
     return ((CredentialsProvider) new DefaultCredentialsProvider(this.clientProperties));
   }
 
+  /**
+   * Returns the default channel provider. The default is gRPC and will default to it unless the
+   * useRest option is provided to use HTTP transport instead
+   */
   @Bean
   @ConditionalOnMissingBean
   public TransportChannelProvider defaultEchoTransportChannelProvider() {
     return EchoSettings.defaultTransportChannelProvider();
   }
 
+  /**
+   * Provides a EchoClient bean configured to use the default credentials provider (obtained with
+   * echoCredentials()) and its default transport channel provider
+   * (defaultEchoTransportChannelProvider()). It also configures the quota project ID if provided.
+   * It will configure an executor provider in case there is more than one thread configured in the
+   * client
+   *
+   * <p>Individual retry settings are configured as well. It will use the relevant client library's
+   * default retry settings when they are not specified in EchoProperties.
+   */
   @Bean
   @ConditionalOnMissingBean
   public EchoClient echoClient(

src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden

@@ -37,6 +37,20 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties
 import org.springframework.context.annotation.Bean;
 import org.threeten.bp.Duration;
 
+// AUTO-GENERATED DOCUMENTATION AND CLASS.
+/**
+ * Auto-configuration for {@link EchoClient}.
+ *
+ * <p>Provides auto-configuration for Spring Boot
+ *
+ * <p>The default instance has everything set to sensible defaults:
+ *
+ * <ul>
+ *   <li>The default transport provider is used.
+ *   <li>Credentials are acquired automatically through Application Default Credentials.
+ *   <li>Retries are configured for idempotent methods but not for non-idempotent methods.
+ * </ul>
+ */
 @Generated("by gapic-generator-java")
 @BetaApi("Autogenerated Spring autoconfiguration is not yet stable")
 @AutoConfiguration
@@ -53,18 +67,36 @@ public class EchoSpringAutoConfiguration {
     this.clientProperties = clientProperties;
   }
 
+  /**
+   * Obtains the default credentials provider. The used key will be obtained from Spring Boot
+   * configuration data files.
+   */
   @Bean
   @ConditionalOnMissingBean
   public CredentialsProvider echoCredentials() throws IOException {
     return ((CredentialsProvider) new DefaultCredentialsProvider(this.clientProperties));
   }
 
+  /**
+   * Returns the default channel provider. The default is gRPC and will default to it unless the
+   * useRest option is provided to use HTTP transport instead
+   */
   @Bean
   @ConditionalOnMissingBean
   public TransportChannelProvider defaultEchoTransportChannelProvider() {
     return EchoSettings.defaultTransportChannelProvider();
   }
 
+  /**
+   * Provides a EchoClient bean configured to use the default credentials provider (obtained with
+   * echoCredentials()) and its default transport channel provider
+   * (defaultEchoTransportChannelProvider()). It also configures the quota project ID if provided.
+   * It will configure an executor provider in case there is more than one thread configured in the
+   * client
+   *
+   * <p>Individual retry settings are configured as well. It will use the relevant client library's
+   * default retry settings when they are not specified in EchoProperties.
+   */
   @Bean
   @ConditionalOnMissingBean
   public EchoClient echoClient(

src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringProperties.golden

@@ -5,6 +5,8 @@ import com.google.cloud.spring.core.CredentialsSupplier;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.threeten.bp.Duration;
 
+// AUTO-GENERATED DOCUMENTATION AND CLASS.
+/** Provides default property values for Echo client bean */
 @ConfigurationProperties("com.google.showcase.v1beta1.spring.auto.echo")
 public class EchoSpringProperties implements CredentialsSupplier {
   @NestedConfigurationProperty

src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringPropertiesFull.golden

@@ -23,6 +23,8 @@ import javax.annotation.Generated;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.threeten.bp.Duration;
 
+// AUTO-GENERATED DOCUMENTATION AND CLASS.
+/** Provides default property values for Echo client bean */
 @Generated("by gapic-generator-java")
 @BetaApi("Autogenerated Spring autoconfiguration is not yet stable")
 @ConfigurationProperties("com.google.showcase.v1beta1.spring.auto.echo")