From 47c8d6ac4144719160df0505bb38a88a0a54dd73 Mon Sep 17 00:00:00 2001 From: Matteo Merli Date: Tue, 17 Mar 2026 15:13:24 -0700 Subject: [PATCH] Add javadoc to all public API in generated gRPC service classes Generated gRPC service classes (e.g., TestServiceGrpc) now have javadoc on all public methods and inner types: - Class-level: uses proto service comment (already present) - getXxxMethod(): uses proto method doc or default description - newStub() / newBlockingStub(): factory method descriptions - getServiceDescriptor() / bindService(): utility descriptions - AsyncService, ImplBase, Stub, BlockingStub: class-level docs --- .../lightproto/generator/LightProtoService.java | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/code-generator/src/main/java/io/streamnative/lightproto/generator/LightProtoService.java b/code-generator/src/main/java/io/streamnative/lightproto/generator/LightProtoService.java index f767c8a..172338e 100644 --- a/code-generator/src/main/java/io/streamnative/lightproto/generator/LightProtoService.java +++ b/code-generator/src/main/java/io/streamnative/lightproto/generator/LightProtoService.java @@ -78,10 +78,12 @@ public void generate(PrintWriter w) { } // Factory methods + w.format(" /** Creates a new async stub for the {@code %s} service. */\n", serviceName); w.format(" public static %sStub newStub(io.grpc.Channel channel) {\n", serviceName); w.format(" return %sStub.newStub(new %sStub.%sStubFactory(), channel);\n", serviceName, serviceName, serviceName); w.format(" }\n\n"); + w.format(" /** Creates a new blocking stub for the {@code %s} service. */\n", serviceName); w.format(" public static %sBlockingStub newBlockingStub(io.grpc.Channel channel) {\n", serviceName); w.format(" return %sBlockingStub.newStub(new %sBlockingStub.%sBlockingStubFactory(), channel);\n", serviceName, serviceName, serviceName); @@ -175,6 +177,11 @@ private void generateMethodDescriptor(PrintWriter w, ProtoMethodDescriptor m, St w.format(" private static volatile io.grpc.MethodDescriptor<%s, %s> %s;\n\n", inputType, outputType, fieldName); + if (m.getDoc() != null && !m.getDoc().isEmpty()) { + Util.writeJavadoc(w, m.getDoc(), " "); + } else { + w.format(" /** Returns the method descriptor for the {@code %s} RPC. */\n", methodName); + } w.format(" public static io.grpc.MethodDescriptor<%s, %s> %s() {\n", inputType, outputType, getterName); w.format(" io.grpc.MethodDescriptor<%s, %s> result;\n", inputType, outputType); @@ -197,6 +204,8 @@ private void generateMethodDescriptor(PrintWriter w, ProtoMethodDescriptor m, St } private void generateAsyncService(PrintWriter w, List methods) { + w.format(" /** Async service interface for the {@code %s} service. */\n", + service.getName()); w.println(" public interface AsyncService {"); for (ProtoMethodDescriptor m : methods) { String ccMethod = javaMethodName(m.getName()); @@ -222,6 +231,7 @@ private void generateAsyncService(PrintWriter w, List met } private void generateImplBase(PrintWriter w, String serviceName) { + w.format(" /** Base implementation of the {@code %s} service. */\n", serviceName); w.format(" public static abstract class %sImplBase implements io.grpc.BindableService, AsyncService {\n", serviceName); w.format(" @Override\n"); @@ -234,6 +244,7 @@ private void generateImplBase(PrintWriter w, String serviceName) { private void generateStub(PrintWriter w, String serviceName, List methods) { String stubName = serviceName + "Stub"; + w.format(" /** Async stub for the {@code %s} service. */\n", serviceName); w.format(" public static final class %s extends io.grpc.stub.AbstractStub<%s> {\n", stubName, stubName); w.format(" private %s(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {\n", stubName); w.format(" super(channel, callOptions);\n"); @@ -292,6 +303,7 @@ private void generateStub(PrintWriter w, String serviceName, List methods) { String stubName = serviceName + "BlockingStub"; + w.format(" /** Blocking stub for the {@code %s} service. */\n", serviceName); w.format(" public static final class %s extends io.grpc.stub.AbstractStub<%s> {\n", stubName, stubName); w.format(" private %s(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {\n", stubName); w.format(" super(channel, callOptions);\n"); @@ -397,6 +409,8 @@ private void generateMethodHandlers(PrintWriter w, String serviceName, List methods) { w.format(" private static volatile io.grpc.ServiceDescriptor serviceDescriptor;\n\n"); + w.format(" /** Returns the service descriptor for the {@code %s} service. */\n", + grpcClassName.replace("Grpc", "")); w.format(" public static io.grpc.ServiceDescriptor getServiceDescriptor() {\n"); w.format(" io.grpc.ServiceDescriptor result = serviceDescriptor;\n"); w.format(" if (result == null) {\n"); @@ -417,6 +431,7 @@ private void generateServiceDescriptor(PrintWriter w, String grpcClassName, List } private void generateBindService(PrintWriter w, List methods) { + w.println(" /** Binds the given {@code AsyncService} implementation and returns a {@code ServerServiceDefinition}. */"); w.println(" public static io.grpc.ServerServiceDefinition bindService(AsyncService service) {"); w.println(" return io.grpc.ServerServiceDefinition.builder(getServiceDescriptor())"); for (ProtoMethodDescriptor m : methods) {