googleapis · miraleung · Sep 4, 2020 · Aug 31, 2020 · Aug 31, 2020 · Sep 1, 2020
diff --git a/src/main/java/com/google/api/generator/engine/ast/ClassDefinition.java b/src/main/java/com/google/api/generator/engine/ast/ClassDefinition.java
@@ -17,6 +17,7 @@
 import com.google.auto.value.AutoValue;
 import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableList;
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 import javax.annotation.Nullable;
@@ -85,8 +86,16 @@ public static Builder builder() {
 
   @AutoValue.Builder
   public abstract static class Builder {
+    public Builder setFileHeader(CommentStatement... headerComments) {
+      return setFileHeader(Arrays.asList(headerComments));
+    }
+
     public abstract Builder setFileHeader(List<CommentStatement> fileHeader);
 
+    public Builder setHeaderCommentStatements(CommentStatement... comments) {
+      return setHeaderCommentStatements(Arrays.asList(comments));
+    }
+
     public abstract Builder setHeaderCommentStatements(
         List<CommentStatement> headerCommentStatements);
 

diff --git a/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java b/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java
@@ -28,6 +28,11 @@ public abstract class JavaDocComment implements Comment {
   @Override
   public abstract String comment();
 
+  // Convenience helper for simple comments.
+  public static JavaDocComment withComment(String comment) {
+    return builder().addComment(comment).build();
+  }
+
   public static Builder builder() {
     return new AutoValue_JavaDocComment.Builder();
   }

diff --git a/src/main/java/com/google/api/generator/engine/ast/MethodDefinition.java b/src/main/java/com/google/api/generator/engine/ast/MethodDefinition.java
@@ -120,6 +120,10 @@ public abstract static class Builder {
 
     public abstract Builder setName(String name);
 
+    public Builder setHeaderCommentStatements(CommentStatement... comments) {
+      return setHeaderCommentStatements(Arrays.asList(comments));
+    }
+
     public abstract Builder setHeaderCommentStatements(
         List<CommentStatement> headeCommentStatements);
 

diff --git a/src/main/java/com/google/api/generator/engine/writer/JavaWriterVisitor.java b/src/main/java/com/google/api/generator/engine/writer/JavaWriterVisitor.java
@@ -725,6 +725,7 @@ public void visit(MethodDefinition methodDefinition) {
 
     rightBrace();
     newline();
+    newline();
   }
 
   @Override
@@ -796,7 +797,9 @@ public void visit(ClassDefinition classDefinition) {
     newline();
 
     statements(classDefinition.statements());
+    newline();
     methods(classDefinition.methods());
+    newline();
     classes(classDefinition.nestedClasses());
 
     rightBrace();

diff --git a/.../generator/gapic/utils/ApacheLicense.java → ...rator/gapic/composer/CommentComposer.java b/.../generator/gapic/utils/ApacheLicense.java → ...rator/gapic/composer/CommentComposer.java
@@ -12,15 +12,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package com.google.api.generator.gapic.utils;
+package com.google.api.generator.gapic.composer;
 
 import com.google.api.generator.engine.ast.BlockComment;
 import com.google.api.generator.engine.ast.CommentStatement;
-import java.util.Arrays;
-import java.util.List;
+import com.google.api.generator.engine.ast.LineComment;
 
-public class ApacheLicense {
-  private static final String fileHeaderString =
+public class CommentComposer {
+  private static final String APACHE_LICENSE_STRING =
       "Copyright 2020 Google LLC\n\n"
           + "Licensed under the Apache License, Version 2.0 (the \"License\");\n"
           + "you may not use this file except in compliance with the License.\n"
@@ -32,6 +31,19 @@ public class ApacheLicense {
           + "See the License for the specific language governing permissions and\n"
           + "limitations under the License.";
 
-  public static final List<CommentStatement> APACHE_LICENSE_COMMENT_STATEMENT =
-      Arrays.asList(CommentStatement.withComment(BlockComment.withComment(fileHeaderString)));
+  private static final String AUTO_GENERATED_CLASS_DISCLAIMER_STRING =
+      "AUTO-GENERATED DOCUMENTATION AND CLASS.";
+
+  private static final String AUTO_GENERATED_METHOD_DISCLAIMER_STRING =
+      "AUTO-GENERATED DOCUMENTATION AND METHOD.";
+
+  public static final CommentStatement APACHE_LICENSE_COMMENT =
+      CommentStatement.withComment(BlockComment.withComment(APACHE_LICENSE_STRING));
+
+  public static final CommentStatement AUTO_GENERATED_CLASS_COMMENT =
+      CommentStatement.withComment(LineComment.withComment(AUTO_GENERATED_CLASS_DISCLAIMER_STRING));
+
+  public static final CommentStatement AUTO_GENERATED_METHOD_COMMENT =
+      CommentStatement.withComment(
+          LineComment.withComment(AUTO_GENERATED_METHOD_DISCLAIMER_STRING));
 }
diff --git a/src/main/java/com/google/api/generator/gapic/composer/Composer.java b/src/main/java/com/google/api/generator/gapic/composer/Composer.java
@@ -23,7 +23,6 @@
 import com.google.api.generator.gapic.model.Message;
 import com.google.api.generator.gapic.model.ResourceName;
 import com.google.api.generator.gapic.model.Service;
-import com.google.api.generator.gapic.utils.ApacheLicense;
 import com.google.common.annotations.VisibleForTesting;
 import java.util.ArrayList;
 import java.util.List;
@@ -117,7 +116,7 @@ protected static List<GapicClass> addApacheLicense(List<GapicClass> gapicClassLi
                   gapicClass
                       .classDefinition()
                       .toBuilder()
-                      .setFileHeader(ApacheLicense.APACHE_LICENSE_COMMENT_STATEMENT)
+                      .setFileHeader(CommentComposer.APACHE_LICENSE_COMMENT)
                       .build();
               return GapicClass.create(gapicClass.kind(), classWithHeader);
             })

diff --git a/src/main/java/com/google/api/generator/gapic/composer/ServiceStubSettingsClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/ServiceStubSettingsClassComposer.java
@@ -103,6 +103,7 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.function.BiFunction;
 import java.util.function.Function;
 import java.util.stream.Collectors;
 import javax.annotation.Generated;
@@ -123,6 +124,8 @@ public class ServiceStubSettingsClassComposer {
       "RETRYABLE_CODE_DEFINITIONS";
   private static final String NESTED_RETRY_PARAM_DEFINITIONS_VAR_NAME = "RETRY_PARAM_DEFINITIONS";
   private static final String STUB_PATTERN = "%sStub";
+
+  private static final String OPERATION_SETTINGS_LITERAL = "OperationSettings";
   private static final String SETTINGS_LITERAL = "Settings";
 
   private static final String LEFT_BRACE = "{";
@@ -160,6 +163,7 @@ public GapicClass generate(
     ClassDefinition classDef =
         ClassDefinition.builder()
             .setPackageString(pakkage)
+            .setHeaderCommentStatements(CommentComposer.AUTO_GENERATED_CLASS_COMMENT)
             .setAnnotations(createClassAnnotations())
             .setScope(ScopeNode.PUBLIC)
             .setName(className)
@@ -230,9 +234,11 @@ private static List<Statement> createClassStatements(
       Map<String, VariableExpr> methodSettingsMemberVarExprs,
       Map<String, Message> messageTypes,
       Map<String, TypeNode> types) {
-    List<Expr> memberVarExprs = new ArrayList<>();
+    Function<Expr, Statement> exprToStatementFn = e -> ExprStatement.withExpr(e);
+    List<Statement> statements = new ArrayList<>();
 
     // Assign DEFAULT_SERVICE_SCOPES.
+    statements.add(ServiceStubSettingsCommentComposer.DEFAULT_SCOPES_COMMENT);
     VariableExpr defaultServiceScopesDeclVarExpr =
         DEFAULT_SERVICE_SCOPES_VAR_EXPR
             .toBuilder()
@@ -263,38 +269,43 @@ private static List<Statement> createClassStatements(
             .setReturnType(DEFAULT_SERVICE_SCOPES_VAR_EXPR.type())
             .build();
 
-    memberVarExprs.add(
-        AssignmentExpr.builder()
-            .setVariableExpr(defaultServiceScopesDeclVarExpr)
-            .setValueExpr(listBuilderExpr)
-            .build());
+    statements.add(
+        exprToStatementFn.apply(
+            AssignmentExpr.builder()
+                .setVariableExpr(defaultServiceScopesDeclVarExpr)
+                .setValueExpr(listBuilderExpr)
+                .build()));
 
     // Declare settings members.
-    memberVarExprs.addAll(
+    statements.addAll(
         methodSettingsMemberVarExprs.values().stream()
             .map(
                 v ->
-                    v.toBuilder()
-                        .setIsDecl(true)
-                        .setScope(ScopeNode.PRIVATE)
-                        .setIsFinal(true)
-                        .build())
+                    exprToStatementFn.apply(
+                        v.toBuilder()
+                            .setIsDecl(true)
+                            .setScope(ScopeNode.PRIVATE)
+                            .setIsFinal(true)
+                            .build()))
             .collect(Collectors.toList()));
 
-    memberVarExprs.addAll(
-        createPagingStaticAssignExprs(service, serviceConfig, messageTypes, types));
+    statements.addAll(
+        createPagingStaticAssignExprs(service, serviceConfig, messageTypes, types).stream()
+            .map(e -> exprToStatementFn.apply(e))
+            .collect(Collectors.toList()));
 
     for (Method method : service.methods()) {
       Optional<GapicBatchingSettings> batchingSettingOpt =
           serviceConfig.getBatchingSetting(service, method);
       if (batchingSettingOpt.isPresent()) {
-        memberVarExprs.add(
-            BatchingDescriptorComposer.createBatchingDescriptorFieldDeclExpr(
-                method, batchingSettingOpt.get(), messageTypes));
+        statements.add(
+            exprToStatementFn.apply(
+                BatchingDescriptorComposer.createBatchingDescriptorFieldDeclExpr(
+                    method, batchingSettingOpt.get(), messageTypes)));
       }
     }
 
-    return memberVarExprs.stream().map(e -> ExprStatement.withExpr(e)).collect(Collectors.toList());
+    return statements;
   }
 
   private static List<Expr> createPagingStaticAssignExprs(
@@ -703,7 +714,6 @@ private static List<MethodDefinition> createClassMethods(
     javaMethods.addAll(createDefaultHelperAndGetterMethods(service, types));
     javaMethods.addAll(createBuilderHelperMethods(service, types));
     javaMethods.add(createClassConstructor(service, methodSettingsMemberVarExprs, types));
-    // TODO(miraleung): Fill this out.
     return javaMethods;
   }
 
@@ -712,6 +722,9 @@ private static List<MethodDefinition> createMethodSettingsGetterMethods(
     Function<Map.Entry<String, VariableExpr>, MethodDefinition> varToMethodFn =
         e ->
             MethodDefinition.builder()
+                .setHeaderCommentStatements(
+                    ServiceStubSettingsCommentComposer.createCallSettingsGetterComment(
+                        getMethodNameFromSettingsVarName(e.getKey())))
                 .setScope(ScopeNode.PUBLIC)
                 .setReturnType(e.getValue().type())
                 .setName(e.getKey())
@@ -806,6 +819,8 @@ private static List<MethodDefinition> createDefaultHelperAndGetterMethods(
             ConcreteReference.withClazz(InstantiatingExecutorProvider.Builder.class));
     javaMethods.add(
         MethodDefinition.builder()
+            .setHeaderCommentStatements(
+                ServiceStubSettingsCommentComposer.DEFAULT_EXECUTOR_PROVIDER_BUILDER_METHOD_COMMENT)
             .setScope(ScopeNode.PUBLIC)
             .setIsStatic(true)
             .setReturnType(returnType)
@@ -822,6 +837,8 @@ private static List<MethodDefinition> createDefaultHelperAndGetterMethods(
     returnType = TypeNode.STRING;
     javaMethods.add(
         MethodDefinition.builder()
+            .setHeaderCommentStatements(
+                ServiceStubSettingsCommentComposer.DEFAULT_SERVICE_ENDPOINT_METHOD_COMMENT)
             .setScope(ScopeNode.PUBLIC)
             .setIsStatic(true)
             .setReturnType(returnType)
@@ -838,6 +855,8 @@ private static List<MethodDefinition> createDefaultHelperAndGetterMethods(
                 .build());
     javaMethods.add(
         MethodDefinition.builder()
+            .setHeaderCommentStatements(
+                ServiceStubSettingsCommentComposer.DEFAULT_SERVICE_SCOPES_METHOD_COMMENT)
             .setScope(ScopeNode.PUBLIC)
             .setIsStatic(true)
             .setReturnType(returnType)
@@ -863,6 +882,9 @@ private static List<MethodDefinition> createDefaultHelperAndGetterMethods(
             .build();
     javaMethods.add(
         MethodDefinition.builder()
+            .setHeaderCommentStatements(
+                ServiceStubSettingsCommentComposer
+                    .DEFAULT_CREDENTIALS_PROVIDER_BUILDER_METHOD_COMMENT)
             .setScope(ScopeNode.PUBLIC)
             .setIsStatic(true)
             .setReturnType(returnType)
@@ -893,6 +915,9 @@ private static List<MethodDefinition> createDefaultHelperAndGetterMethods(
             .build();
     javaMethods.add(
         MethodDefinition.builder()
+            .setHeaderCommentStatements(
+                ServiceStubSettingsCommentComposer
+                    .DEFAULT_GRPC_TRANSPORT_PROVIDER_BUILDER_METHOD_COMMENT)
             .setScope(ScopeNode.PUBLIC)
             .setIsStatic(true)
             .setReturnType(returnType)
@@ -993,6 +1018,8 @@ private static List<MethodDefinition> createBuilderHelperMethods(
     final TypeNode builderReturnType = types.get(NESTED_BUILDER_CLASS_NAME);
     javaMethods.add(
         MethodDefinition.builder()
+            .setHeaderCommentStatements(
+                ServiceStubSettingsCommentComposer.NEW_BUILDER_METHOD_COMMENT)
             .setScope(ScopeNode.PUBLIC)
             .setIsStatic(true)
             .setReturnType(builderReturnType)
@@ -1016,6 +1043,8 @@ private static List<MethodDefinition> createBuilderHelperMethods(
                 .build());
     javaMethods.add(
         MethodDefinition.builder()
+            .setHeaderCommentStatements(
+                ServiceStubSettingsCommentComposer.NEW_BUILDER_METHOD_COMMENT)
             .setScope(ScopeNode.PUBLIC)
             .setIsStatic(true)
             .setReturnType(builderReturnType)
@@ -1027,6 +1056,8 @@ private static List<MethodDefinition> createBuilderHelperMethods(
     // Create the toBuilder method.
     javaMethods.add(
         MethodDefinition.builder()
+            .setHeaderCommentStatements(
+                ServiceStubSettingsCommentComposer.TO_BUILDER_METHOD_COMMENT)
             .setScope(ScopeNode.PUBLIC)
             .setReturnType(builderReturnType)
             .setName("toBuilder")
@@ -1116,6 +1147,9 @@ private static ClassDefinition createNestedBuilderClass(
     // TODO(miraleung): Fill this out.
     return ClassDefinition.builder()
         .setIsNested(true)
+        .setHeaderCommentStatements(
+            ServiceStubSettingsCommentComposer.createBuilderClassComment(
+                getThisClassName(service.name())))
         .setScope(ScopeNode.PUBLIC)
         .setIsStatic(true)
         .setName(className)
@@ -1333,12 +1367,10 @@ private static List<MethodDefinition> createNestedClassConstructorMethods(
                   // Name is fooBarSettings.
                   VariableExpr varExpr = e.getValue();
                   TypeNode varType = varExpr.type();
-                  String methodName = e.getKey();
                   Preconditions.checkState(
-                      methodName.endsWith(SETTINGS_LITERAL),
-                      String.format("%s expected to end with \"Settings\"", methodName));
-                  methodName =
-                      methodName.substring(0, methodName.length() - SETTINGS_LITERAL.length());
+                      e.getKey().endsWith(SETTINGS_LITERAL),
+                      String.format("%s expected to end with \"Settings\"", e.getKey()));
+                  String methodName = getMethodNameFromSettingsVarName(e.getKey());
 
                   if (!isPagedCallSettingsBuilderFn.apply(varType)) {
                     if (!isBatchingCallSettingsBuilderFn.apply(varType)) {
@@ -1621,8 +1653,9 @@ private static MethodDefinition createNestedClassApplyToAllUnaryMethodsMethod(
     TypeNode returnType = types.get(NESTED_BUILDER_CLASS_NAME);
     Expr returnExpr = ValueExpr.withValue(ThisObjectValue.withType(returnType));
 
-    // TODO(miraleung): Add major ver note.
     return MethodDefinition.builder()
+        .setHeaderCommentStatements(
+            ServiceStubSettingsCommentComposer.APPLY_TO_ALL_UNARY_METHODS_METHOD_COMMENTS)
         .setScope(ScopeNode.PUBLIC)
         .setReturnType(returnType)
         .setName(methodName)
@@ -1669,6 +1702,9 @@ private static List<MethodDefinition> createNestedClassSettingsBuilderGetterMeth
           isOperationCallSettingsBuilderFn.apply(settingsVarExpr.type());
       javaMethods.add(
           MethodDefinition.builder()
+              .setHeaderCommentStatements(
+                  ServiceStubSettingsCommentComposer.createCallSettingsBuilderGetterComment(
+                      getMethodNameFromSettingsVarName(varName)))
               .setAnnotations(isOperationCallSettings ? lroBetaAnnotations : ImmutableList.of())
               .setScope(ScopeNode.PUBLIC)
               .setReturnType(settingsVarExpr.type())
@@ -1964,4 +2000,17 @@ private static TypeNode getOperationCallSettingsType(Method method, boolean isSe
             .setGenerics(generics)
             .build());
   }
+
+  /** Turns a name like "waitSettings" or "waitOperationSettings" into "wait". */
+  private static String getMethodNameFromSettingsVarName(String settingsVarName) {
+    BiFunction<String, String, String> methodNameSubstrFn =
+        (s, literal) -> s.substring(0, s.length() - literal.length());
+    if (settingsVarName.endsWith(OPERATION_SETTINGS_LITERAL)) {
+      return methodNameSubstrFn.apply(settingsVarName, OPERATION_SETTINGS_LITERAL);
+    }
+    if (settingsVarName.endsWith(SETTINGS_LITERAL)) {
+      return methodNameSubstrFn.apply(settingsVarName, SETTINGS_LITERAL);
+    }
+    return settingsVarName;
+  }
 }