[ggj][codegen] feat: add comments for Resnames

src/main/java/com/google/api/generator/engine/writer/JavaWriterVisitor.java

@@ -836,6 +836,7 @@ private void classes(List<ClassDefinition> classes) {
     for (ClassDefinition classDef : classes) {
       classDef.accept(this);
       newline();
+      newline();
     }
   }
 

src/main/java/com/google/api/generator/gapic/composer/ResourceNameHelperClassComposer.java

@@ -18,11 +18,13 @@
 import com.google.api.generator.engine.ast.AnnotationNode;
 import com.google.api.generator.engine.ast.AssignmentExpr;
 import com.google.api.generator.engine.ast.ClassDefinition;
+import com.google.api.generator.engine.ast.CommentStatement;
 import com.google.api.generator.engine.ast.ConcreteReference;
 import com.google.api.generator.engine.ast.Expr;
 import com.google.api.generator.engine.ast.ExprStatement;
 import com.google.api.generator.engine.ast.ForStatement;
 import com.google.api.generator.engine.ast.IfStatement;
+import com.google.api.generator.engine.ast.JavaDocComment;
 import com.google.api.generator.engine.ast.MethodDefinition;
 import com.google.api.generator.engine.ast.MethodInvocationExpr;
 import com.google.api.generator.engine.ast.NewObjectExpr;
@@ -69,6 +71,8 @@ public class ResourceNameHelperClassComposer {
   private static final String LEFT_BRACE = "{";
   private static final String RIGHT_BRACE = "}";
 
+  private static final String BUILDER_CLASS_HEADER_PATTERN = "Builder for %s.";
+
   private static final ResourceNameHelperClassComposer INSTANCE =
       new ResourceNameHelperClassComposer();
 
@@ -107,6 +111,7 @@ public GapicClass generate(ResourceName resourceName) {
     ClassDefinition classDef =
         ClassDefinition.builder()
             .setPackageString(resourceName.pakkage())
+            .setHeaderCommentStatements(CommentComposer.AUTO_GENERATED_CLASS_COMMENT)
             .setAnnotations(createClassAnnotations())
             .setScope(ScopeNode.PUBLIC)
             .setName(className)
@@ -1323,6 +1328,10 @@ private static ClassDefinition createNestedBuilderClass(
         isDefaultClass ? Collections.emptyList() : Arrays.asList(betaAnnotation);
 
     return ClassDefinition.builder()
+        .setHeaderCommentStatements(
+            CommentStatement.withComment(
+                JavaDocComment.withComment(
+                    String.format(BUILDER_CLASS_HEADER_PATTERN, resourceNamePattern))))
         .setAnnotations(classAnnotations)
         .setIsNested(true)
         .setScope(ScopeNode.PUBLIC)

src/test/java/com/google/api/generator/engine/JavaCodeGeneratorTest.java

@@ -878,6 +878,7 @@ private ClassDefinition createNestedClassNovel() {
           + "      this.seriesNum = seriesNum;\n"
           + "    }\n"
           + "  }\n"
+          + "\n"
           + "  // Test nested abstract class and abstract method.\n"
           + "  public abstract class Book {\n"
           + "    public BookKind bookKind;\n"

src/test/java/com/google/api/generator/gapic/composer/ResourceNameHelperClassComposerTest.java

@@ -220,6 +220,7 @@ public void generateResourceNameClass_testingSessionOnePattern() {
           + "import java.util.Objects;\n"
           + "import javax.annotation.Generated;\n"
           + "\n"
+          + "// AUTO-GENERATED DOCUMENTATION AND CLASS.\n"
           + "@Generated(\"by gapic-generator-java\")\n"
           + "public class FoobarName implements ResourceName {\n"
           + "  private static final PathTemplate PROJECT_FOOBAR =\n"
@@ -324,15 +325,13 @@ public void generateResourceNameClass_testingSessionOnePattern() {
           + "  }\n"
           + "\n"
           + "  public static String format(String project, String foobar) {\n"
-          + "    return"
-          + " newBuilder().setProject(project).setFoobar(foobar).build().toString();\n"
+          + "    return newBuilder().setProject(project).setFoobar(foobar).build().toString();\n"
           + "  }\n"
           + "\n"
           + "  @BetaApi(\"The static format methods are not stable yet and may be changed in the"
           + " future.\")\n"
           + "  public static String formatProjectFoobarBuilder(String project, String foobar) {\n"
-          + "    return"
-          + " newBuilder().setProject(project).setFoobar(foobar).build().toString();\n"
+          + "    return newBuilder().setProject(project).setFoobar(foobar).build().toString();\n"
           + "  }\n"
           + "\n"
           + "  @BetaApi(\"The static format methods are not stable yet and may be changed in the"
@@ -435,6 +434,7 @@ public void generateResourceNameClass_testingSessionOnePattern() {
           + "        : fixedValue;\n"
           + "  }\n"
           + "\n"
+          + "  /** Builder for projects/{project}/foobars/{foobar}. */\n"
           + "  public static class Builder {\n"
           + "    private String project;\n"
           + "    private String foobar;\n"
@@ -473,6 +473,8 @@ public void generateResourceNameClass_testingSessionOnePattern() {
           + "    }\n"
           + "  }\n"
           + "\n"
+          + "  /** Builder for projects/{project}/chocolate/variants/{variant}/foobars/{foobar}."
+          + " */\n"
           + "  @BetaApi(\"The per-pattern Builders are not stable yet and may be changed in the"
           + " future.\")\n"
           + "  public static class ProjectVariantFoobarBuilder {\n"
@@ -514,6 +516,7 @@ public void generateResourceNameClass_testingSessionOnePattern() {
           + "    }\n"
           + "  }\n"
           + "\n"
+          + "  /** Builder for foobars/{foobar}. */\n"
           + "  @BetaApi(\"The per-pattern Builders are not stable yet and may be changed in the"
           + " future.\")\n"
           + "  public static class FoobarBuilder {\n"
@@ -549,6 +552,7 @@ public void generateResourceNameClass_testingSessionOnePattern() {
           + "import java.util.Objects;\n"
           + "import javax.annotation.Generated;\n"
           + "\n"
+          + "// AUTO-GENERATED DOCUMENTATION AND CLASS.\n"
           + "@Generated(\"by gapic-generator-java\")\n"
           + "public class SessionName implements ResourceName {\n"
           + "  private static final PathTemplate SESSION =\n"
@@ -641,6 +645,7 @@ public void generateResourceNameClass_testingSessionOnePattern() {
           + "    return SESSION.instantiate(\"session\", session);\n"
           + "  }\n"
           + "\n"
+          + "  /** Builder for sessions/{session}. */\n"
           + "  public static class Builder {\n"
           + "    private String session;\n"
           + "\n"