[ggj][codegen] fix: add back method comment for protected ctors in GrpcServiceStub (#592)

* fix: fix dep ordering in Bazel dedupe rules

* fix: use lowerCamelCase param names in ServiceClient JavaDocs

* fix: add HTTP's additional_bindings to GrpcServiceStub call settings

* fix: add back method comment for protected ctors in GrpcServiceStub

Author: miraleung

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

@@ -29,11 +29,13 @@
 import com.google.api.generator.engine.ast.AnonymousClassExpr;
 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.EmptyLineStatement;
 import com.google.api.generator.engine.ast.EnumRefExpr;
 import com.google.api.generator.engine.ast.Expr;
 import com.google.api.generator.engine.ast.ExprStatement;
+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;
@@ -525,6 +527,8 @@ private static List<MethodDefinition> createConstructorMethods(
             MethodDefinition.constructorBuilder()
                 .setScope(ScopeNode.PROTECTED)
                 .setReturnType(thisClassType)
+                .setHeaderCommentStatements(
+                    Arrays.asList(createProtectedCtorComment(service.name())))
                 .setArguments(
                     args.stream()
                         .map(v -> v.toBuilder().setIsDecl(true).build())
@@ -1143,4 +1147,14 @@ private static String getProtoRpcFullMethodName(Service protoService, Method pro
   private static String getThisClassName(String serviceName) {
     return String.format(CLASS_NAME_PATTERN, serviceName);
   }
+
+  private static CommentStatement createProtectedCtorComment(String serviceName) {
+    return CommentStatement.withComment(
+        JavaDocComment.withComment(
+            String.format(
+                "Constructs an instance of %s, using the given settings. This is protected so that"
+                    + " it is easy to make a subclass, but otherwise, the static factory methods"
+                    + " should be  preferred.",
+                getThisClassName(serviceName))));
+  }
 }

src/test/java/com/google/api/generator/gapic/composer/goldens/GrpcEchoStub.golden

@@ -147,11 +147,19 @@ public class GrpcEchoStub extends EchoStub {
     return new GrpcEchoStub(EchoStubSettings.newBuilder().build(), clientContext, callableFactory);
   }
 
+  /**
+   * Constructs an instance of GrpcEchoStub, using the given settings. This is protected so that it
+   * is easy to make a subclass, but otherwise, the static factory methods should be preferred.
+   */
   protected GrpcEchoStub(EchoStubSettings settings, ClientContext clientContext)
       throws IOException {
     this(settings, clientContext, new GrpcEchoCallableFactory());
   }
 
+  /**
+   * Constructs an instance of GrpcEchoStub, using the given settings. This is protected so that it
+   * is easy to make a subclass, but otherwise, the static factory methods should be preferred.
+   */
   protected GrpcEchoStub(
       EchoStubSettings settings,
       ClientContext clientContext,

src/test/java/com/google/api/generator/gapic/composer/goldens/GrpcPublisherStub.golden

@@ -163,11 +163,21 @@ public class GrpcPublisherStub extends PublisherStub {
         PublisherStubSettings.newBuilder().build(), clientContext, callableFactory);
   }
 
+  /**
+   * Constructs an instance of GrpcPublisherStub, using the given settings. This is protected so
+   * that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcPublisherStub(PublisherStubSettings settings, ClientContext clientContext)
       throws IOException {
     this(settings, clientContext, new GrpcPublisherCallableFactory());
   }
 
+  /**
+   * Constructs an instance of GrpcPublisherStub, using the given settings. This is protected so
+   * that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcPublisherStub(
       PublisherStubSettings settings,
       ClientContext clientContext,

src/test/java/com/google/api/generator/gapic/composer/goldens/GrpcTestingStub.golden

@@ -155,11 +155,19 @@ public class GrpcTestingStub extends TestingStub {
         TestingStubSettings.newBuilder().build(), clientContext, callableFactory);
   }
 
+  /**
+   * Constructs an instance of GrpcTestingStub, using the given settings. This is protected so that
+   * it is easy to make a subclass, but otherwise, the static factory methods should be preferred.
+   */
   protected GrpcTestingStub(TestingStubSettings settings, ClientContext clientContext)
       throws IOException {
     this(settings, clientContext, new GrpcTestingCallableFactory());
   }
 
+  /**
+   * Constructs an instance of GrpcTestingStub, using the given settings. This is protected so that
+   * it is easy to make a subclass, but otherwise, the static factory methods should be preferred.
+   */
   protected GrpcTestingStub(
       TestingStubSettings settings,
       ClientContext clientContext,

test/integration/goldens/asset/GrpcAssetServiceStub.java

@@ -182,11 +182,21 @@ public static final GrpcAssetServiceStub create(
         AssetServiceStubSettings.newBuilder().build(), clientContext, callableFactory);
   }
 
+  /**
+   * Constructs an instance of GrpcAssetServiceStub, using the given settings. This is protected so
+   * that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcAssetServiceStub(AssetServiceStubSettings settings, ClientContext clientContext)
       throws IOException {
     this(settings, clientContext, new GrpcAssetServiceCallableFactory());
   }
 
+  /**
+   * Constructs an instance of GrpcAssetServiceStub, using the given settings. This is protected so
+   * that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcAssetServiceStub(
       AssetServiceStubSettings settings,
       ClientContext clientContext,

test/integration/goldens/library/GrpcLibraryServiceStub.java

@@ -186,11 +186,21 @@ public static final GrpcLibraryServiceStub create(
         LibraryServiceStubSettings.newBuilder().build(), clientContext, callableFactory);
   }
 
+  /**
+   * Constructs an instance of GrpcLibraryServiceStub, using the given settings. This is protected
+   * so that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcLibraryServiceStub(LibraryServiceStubSettings settings, ClientContext clientContext)
       throws IOException {
     this(settings, clientContext, new GrpcLibraryServiceCallableFactory());
   }
 
+  /**
+   * Constructs an instance of GrpcLibraryServiceStub, using the given settings. This is protected
+   * so that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcLibraryServiceStub(
       LibraryServiceStubSettings settings,
       ClientContext clientContext,

test/integration/goldens/logging/GrpcConfigServiceV2Stub.java

@@ -247,11 +247,21 @@ public static final GrpcConfigServiceV2Stub create(
         ConfigServiceV2StubSettings.newBuilder().build(), clientContext, callableFactory);
   }
 
+  /**
+   * Constructs an instance of GrpcConfigServiceV2Stub, using the given settings. This is protected
+   * so that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcConfigServiceV2Stub(
       ConfigServiceV2StubSettings settings, ClientContext clientContext) throws IOException {
     this(settings, clientContext, new GrpcConfigServiceV2CallableFactory());
   }
 
+  /**
+   * Constructs an instance of GrpcConfigServiceV2Stub, using the given settings. This is protected
+   * so that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcConfigServiceV2Stub(
       ConfigServiceV2StubSettings settings,
       ClientContext clientContext,

test/integration/goldens/logging/GrpcLoggingServiceV2Stub.java

@@ -146,11 +146,21 @@ public static final GrpcLoggingServiceV2Stub create(
         LoggingServiceV2StubSettings.newBuilder().build(), clientContext, callableFactory);
   }
 
+  /**
+   * Constructs an instance of GrpcLoggingServiceV2Stub, using the given settings. This is protected
+   * so that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcLoggingServiceV2Stub(
       LoggingServiceV2StubSettings settings, ClientContext clientContext) throws IOException {
     this(settings, clientContext, new GrpcLoggingServiceV2CallableFactory());
   }
 
+  /**
+   * Constructs an instance of GrpcLoggingServiceV2Stub, using the given settings. This is protected
+   * so that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcLoggingServiceV2Stub(
       LoggingServiceV2StubSettings settings,
       ClientContext clientContext,

test/integration/goldens/logging/GrpcMetricsServiceV2Stub.java

@@ -129,11 +129,21 @@ public static final GrpcMetricsServiceV2Stub create(
         MetricsServiceV2StubSettings.newBuilder().build(), clientContext, callableFactory);
   }
 
+  /**
+   * Constructs an instance of GrpcMetricsServiceV2Stub, using the given settings. This is protected
+   * so that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcMetricsServiceV2Stub(
       MetricsServiceV2StubSettings settings, ClientContext clientContext) throws IOException {
     this(settings, clientContext, new GrpcMetricsServiceV2CallableFactory());
   }
 
+  /**
+   * Constructs an instance of GrpcMetricsServiceV2Stub, using the given settings. This is protected
+   * so that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcMetricsServiceV2Stub(
       MetricsServiceV2StubSettings settings,
       ClientContext clientContext,

test/integration/goldens/redis/GrpcCloudRedisStub.java

@@ -191,11 +191,21 @@ public static final GrpcCloudRedisStub create(
         CloudRedisStubSettings.newBuilder().build(), clientContext, callableFactory);
   }
 
+  /**
+   * Constructs an instance of GrpcCloudRedisStub, using the given settings. This is protected so
+   * that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcCloudRedisStub(CloudRedisStubSettings settings, ClientContext clientContext)
       throws IOException {
     this(settings, clientContext, new GrpcCloudRedisCallableFactory());
   }
 
+  /**
+   * Constructs an instance of GrpcCloudRedisStub, using the given settings. This is protected so
+   * that it is easy to make a subclass, but otherwise, the static factory methods should be
+   * preferred.
+   */
   protected GrpcCloudRedisStub(
       CloudRedisStubSettings settings,
       ClientContext clientContext,