address PR feedback

vam-google · vam-google · commit 4813464e3cea · 2021-06-15T22:42:34.000-07:00
diff --git a/BUILD.bazel b/BUILD.bazel
@@ -8,6 +8,7 @@ load(
 package(default_visibility = ["//visibility:public"])
 
 JAVA_SRCS = [
+    "//src/main/java/com/google/api/generator/debug:debug_files",
     "//src/main/java/com/google/api/generator:generator_files",
     "//src/main/java/com/google/api/generator/engine:engine_files",
     "//src/main/java/com/google/api/generator/gapic:gapic_files",
@@ -53,6 +54,16 @@ java_binary(
 # directly (instead of relying on protoc to start the process), which would give
 # much greater flexibility in terms of debugging features, like attaching a
 # debugger, easier work with stdout and stderr etc.
+#
+# Usage example, via the rule in a corresponding BUILD.bazel file:
+#
+# load("@gapic_generator_java//rules_java_gapic:java_gapic.bzl", "java_generator_request_dump")
+# java_generator_request_dump(
+#     name = "compute_small_request_dump",
+#     srcs = [":compute_small_proto_with_info"],
+#     transport = "rest",
+# )
+#
 java_binary(
     name = "protoc-gen-code_generator_request_dumper",
     main_class = "com.google.api.generator.debug.CodeGeneratorRequestDumper",
@@ -69,9 +80,14 @@ java_binary(
 
 # A binary similar to protoc-gen-java_gapic but reads the CodeGeneratorRequest
 # directly from a file instead of relying on protoc to pipe it in.
+#
+# Usage example:
+#
+# bazel run code_generator_request_file_to_gapic_main desc-dump.bin dump.jar
+#
 java_binary(
-    name = "protoc-gen-java_gapic_from_file",
-    main_class = "com.google.api.generator.debug.MainStandalone",
+    name = "code_generator_request_file_to_gapic_main",
+    main_class = "com.google.api.generator.debug.CodeGeneratorRequestFileToGapicMain",
     runtime_deps = [
         "//src/main/java/com/google/api/generator",
         "//src/main/java/com/google/api/generator/debug",
diff --git a/src/main/java/com/google/api/generator/debug/CodeGeneratorRequestDumper.java b/src/main/java/com/google/api/generator/debug/CodeGeneratorRequestDumper.java
@@ -20,6 +20,11 @@
 import com.google.protobuf.compiler.PluginProtos.CodeGeneratorResponse;
 import java.io.IOException;
 
+// Request dumper class, which dumps the CodeGeneratorRequest to a file on disk which will be
+// identical to the one passed to the Main class during normal execution. The dumped file then can
+// be used to run this gapic-generator directly (instead of relying on protoc to start the process),
+// which would give much greater flexibility in terms of debugging features, like attaching a
+// debugger, easier work with stdout and stderr etc.
 public class CodeGeneratorRequestDumper {
   public static void main(String[] args) throws IOException {
     ExtensionRegistry registry = ExtensionRegistry.newInstance();
diff --git a/src/main/java/com/google/api/generator/debug/CodeGeneratorRequestFileToGapicMain.java b/src/main/java/com/google/api/generator/debug/CodeGeneratorRequestFileToGapicMain.java
@@ -25,7 +25,9 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 
-public class MainStandalone {
+// A generator entry point class, similar to Main but reads the CodeGeneratorRequest directly from a
+// file instead of relying on protoc to pipe it in.
+public class CodeGeneratorRequestFileToGapicMain {
   public static void main(String[] args) throws IOException {
     ExtensionRegistry registry = ExtensionRegistry.newInstance();
     ProtoRegistry.registerAllExtensions(registry);
