From a1b710cac2c52d35f13e00e7ae0612bc9e6f00dd Mon Sep 17 00:00:00 2001 From: Scott Mitchell Date: Thu, 10 Mar 2022 10:25:09 -0800 Subject: [PATCH 1/3] grpc-protoc fix missing javadoc Motivation: `addService(BlockingX)` was deprecated and javadocs were added to indicate this. However we need to add javadocs for all params/return value or else javadoc lint warnings will be generated. --- .../src/main/java/io/servicetalk/grpc/protoc/Generator.java | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java b/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java index edbf04c7e2..b57dff2f93 100644 --- a/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java +++ b/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java @@ -601,8 +601,12 @@ private TypeSpec.Builder addServiceFactory(final State state, final TypeSpec.Bui serviceBuilderSpecBuilder.addMethod(methodBuilder(addService) .addModifiers(PUBLIC) .addAnnotation(Deprecated.class) - .addJavadoc(JAVADOC_DEPRECATED + "Use {@link #$L($T)}." + lineSeparator(), addBlockingService, + .addJavadoc(JAVADOC_DEPRECATED + "Use {@link #$L($T)}.", addBlockingService, state.blockingServiceClass) + .addJavadoc(lineSeparator()) + .addJavadoc(JAVADOC_PARAM + service + " the service to add.") + .addJavadoc(lineSeparator()) + .addJavadoc(JAVADOC_RETURN + "this.") .returns(builderClass) .addParameter(state.blockingServiceClass, service, FINAL) .addStatement("return $L($L)", addBlockingService, service) From acd697eaba253d3192f65e0e7d6cd88614a5b2c7 Mon Sep 17 00:00:00 2001 From: Scott Mitchell Date: Thu, 10 Mar 2022 10:55:14 -0800 Subject: [PATCH 2/3] review comments --- .../io/servicetalk/grpc/protoc/Generator.java | 32 +++++++++---------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java b/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java index b57dff2f93..0f63e821d0 100644 --- a/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java +++ b/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java @@ -601,11 +601,11 @@ private TypeSpec.Builder addServiceFactory(final State state, final TypeSpec.Bui serviceBuilderSpecBuilder.addMethod(methodBuilder(addService) .addModifiers(PUBLIC) .addAnnotation(Deprecated.class) - .addJavadoc(JAVADOC_DEPRECATED + "Use {@link #$L($T)}.", addBlockingService, + .addJavadoc("Adds a {@link $T} implementation." + lineSeparator(), state.blockingServiceClass) + .addJavadoc(JAVADOC_PARAM + service + " the {@link $T} implementation to add." + lineSeparator(), + state.blockingServiceClass) + .addJavadoc(JAVADOC_DEPRECATED + "Use {@link #$L($T)}." + lineSeparator(), addBlockingService, state.blockingServiceClass) - .addJavadoc(lineSeparator()) - .addJavadoc(JAVADOC_PARAM + service + " the service to add.") - .addJavadoc(lineSeparator()) .addJavadoc(JAVADOC_RETURN + "this.") .returns(builderClass) .addParameter(state.blockingServiceClass, service, FINAL) @@ -877,14 +877,13 @@ private TypeSpec.Builder addClientInterfaces(final State state, final TypeSpec.B printJavaDocs, (methodName, b) -> { ClassName inClass = messageTypesMap.get(clientMetaData.methodProto.getInputType()); b.addModifiers(ABSTRACT).addParameter(clientMetaData.className, metadata) - .addAnnotation(Deprecated.class) - .addJavadoc(JAVADOC_DEPRECATED + "Use {@link #$L($T,$T)}." + lineSeparator(), - methodName, - GrpcClientMetadata, clientMetaData.methodProto.getClientStreaming() ? - Publisher : inClass); + .addAnnotation(Deprecated.class); if (printJavaDocs) { extractJavaDocComments(state, methodIndex, b); - b.addJavadoc(JAVADOC_PARAM + metadata + + b.addJavadoc(JAVADOC_DEPRECATED + "Use {@link #$L($T,$T)}." + lineSeparator(), + methodName, GrpcClientMetadata, + clientMetaData.methodProto.getClientStreaming() ? Publisher : inClass) + .addJavadoc(JAVADOC_PARAM + metadata + " the metadata associated with this client call." + lineSeparator()); } return b; @@ -914,13 +913,13 @@ private TypeSpec.Builder addClientInterfaces(final State state, final TypeSpec.B printJavaDocs, (methodName, b) -> { ClassName inClass = messageTypesMap.get(clientMetaData.methodProto.getInputType()); b.addModifiers(ABSTRACT).addParameter(clientMetaData.className, metadata) - .addAnnotation(Deprecated.class) - .addJavadoc(JAVADOC_DEPRECATED + "Use {@link #$L($T,$T)}." + lineSeparator(), - methodName, GrpcClientMetadata, clientMetaData.methodProto.getClientStreaming() ? - Types.Iterable : inClass); + .addAnnotation(Deprecated.class); if (printJavaDocs) { extractJavaDocComments(state, methodIndex, b); - b.addJavadoc(JAVADOC_PARAM + metadata + + b.addJavadoc(JAVADOC_DEPRECATED + "Use {@link #$L($T,$T)}." + lineSeparator(), + methodName, GrpcClientMetadata, + clientMetaData.methodProto.getClientStreaming() ? Types.Iterable : inClass) + .addJavadoc(JAVADOC_PARAM + metadata + " the metadata associated with this client call." + lineSeparator()); } return b; @@ -1045,8 +1044,7 @@ private static MethodSpec newRpcMethodSpec( if (flags.contains(BLOCKING)) { if (clientSteaming) { if (flags.contains(CLIENT)) { - methodSpecBuilder.addParameter(ParameterizedTypeName.get(ClassName.get(Iterable.class), - inClass), request, mods); + methodSpecBuilder.addParameter(ParameterizedTypeName.get(Types.Iterable, inClass), request, mods); if (printJavaDocs) { methodSpecBuilder.addJavadoc(JAVADOC_PARAM + request + " used to send a stream of type {@link $T} to the server." + lineSeparator(), inClass); From 632da3258093920e8ec2143e791d981e95076243 Mon Sep 17 00:00:00 2001 From: Idel Pivnitskiy Date: Thu, 10 Mar 2022 11:15:58 -0800 Subject: [PATCH 3/3] `@deprecated` after `@return` --- .../src/main/java/io/servicetalk/grpc/protoc/Generator.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java b/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java index 0f63e821d0..e2c3d286f2 100644 --- a/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java +++ b/servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java @@ -602,11 +602,12 @@ private TypeSpec.Builder addServiceFactory(final State state, final TypeSpec.Bui .addModifiers(PUBLIC) .addAnnotation(Deprecated.class) .addJavadoc("Adds a {@link $T} implementation." + lineSeparator(), state.blockingServiceClass) + .addJavadoc(lineSeparator()) .addJavadoc(JAVADOC_PARAM + service + " the {@link $T} implementation to add." + lineSeparator(), state.blockingServiceClass) + .addJavadoc(JAVADOC_RETURN + "this." + lineSeparator()) .addJavadoc(JAVADOC_DEPRECATED + "Use {@link #$L($T)}." + lineSeparator(), addBlockingService, state.blockingServiceClass) - .addJavadoc(JAVADOC_RETURN + "this.") .returns(builderClass) .addParameter(state.blockingServiceClass, service, FINAL) .addStatement("return $L($L)", addBlockingService, service)